[CARBONDATA-2156] Add interface annotation InterfaceAudience and InterfaceStability annotation should be added for user and developer
1.InetfaceAudience can be User and Developer 2.InterfaceStability can be Stable, Evolving, Unstable This closes #1968 Project: http://git-wip-us.apache.org/repos/asf/carbondata/repo Commit: http://git-wip-us.apache.org/repos/asf/carbondata/commit/653c51b1 Tree: http://git-wip-us.apache.org/repos/asf/carbondata/tree/653c51b1 Diff: http://git-wip-us.apache.org/repos/asf/carbondata/diff/653c51b1 Branch: refs/heads/carbonstore-rebase5 Commit: 653c51b1b64e6d55f9483bbca7e1e85869de665e Parents: 78aa2cc Author: Jacky Li <jacky.li...@qq.com> Authored: Sun Feb 11 10:12:10 2018 +0800 Committer: Jacky Li <jacky.li...@qq.com> Committed: Fri Mar 2 15:52:36 2018 +0800 ---------------------------------------------------------------------- .../common/annotations/InterfaceAudience.java | 58 ++++++++++++++++ .../common/annotations/InterfaceStability.java | 69 ++++++++++++++++++++ 2 files changed, 127 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/carbondata/blob/653c51b1/common/src/main/java/org/apache/carbondata/common/annotations/InterfaceAudience.java ---------------------------------------------------------------------- diff --git a/common/src/main/java/org/apache/carbondata/common/annotations/InterfaceAudience.java b/common/src/main/java/org/apache/carbondata/common/annotations/InterfaceAudience.java new file mode 100644 index 0000000..fa9729d --- /dev/null +++ b/common/src/main/java/org/apache/carbondata/common/annotations/InterfaceAudience.java @@ -0,0 +1,58 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.carbondata.common.annotations; + +import java.lang.annotation.Documented; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; + +/** + * This annotation is ported and modified from Apache Hadoop project. + * + * Annotation to inform users of a package, class or method's intended audience. + * Currently the audience can be {@link User}, {@link Developer} + * + * Public classes that are not marked with this annotation must be + * considered by default as {@link Developer}.</li> + * + * External applications must only use classes that are marked {@link User}. + * + * Methods may have a different annotation that it is more restrictive + * compared to the audience classification of the class. Example: A class + * might be {@link User}, but a method may be {@link Developer} + */ +@InterfaceAudience.User +@InterfaceStability.Evolving +public class InterfaceAudience { + /** + * Intended for use by any project or application. + */ + @Documented + @Retention(RetentionPolicy.RUNTIME) + public @interface User { } + + /** + * Intended only for developers to extend interface for CarbonData project + * For example, new Datamap implementations. + */ + @Documented + @Retention(RetentionPolicy.RUNTIME) + public @interface Developer { } + + private InterfaceAudience() { } // Audience can't exist on its own +} http://git-wip-us.apache.org/repos/asf/carbondata/blob/653c51b1/common/src/main/java/org/apache/carbondata/common/annotations/InterfaceStability.java ---------------------------------------------------------------------- diff --git a/common/src/main/java/org/apache/carbondata/common/annotations/InterfaceStability.java b/common/src/main/java/org/apache/carbondata/common/annotations/InterfaceStability.java new file mode 100644 index 0000000..b8e5e52 --- /dev/null +++ b/common/src/main/java/org/apache/carbondata/common/annotations/InterfaceStability.java @@ -0,0 +1,69 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.carbondata.common.annotations; + +import java.lang.annotation.Documented; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; + +import org.apache.carbondata.common.annotations.InterfaceAudience.*; + +/** + * This annotation is ported and modified from Apache Hadoop project. + * + * Annotation to inform users of how much to rely on a particular package, + * class or method not changing over time. Currently the stability can be + * {@link Stable}, {@link Evolving} or {@link Unstable}. <br> + * + * 1. {@link Stable} means compatibility can break only at major release (m.0) + * 2. {@link Evolving} means compatibility can break at minor release (m.x) + * 3. {@link Unstable} means compatibility can break at any release + * + * <ul><li>All classes that are annotated with {@link User} or + * {@link Developer} must have InterfaceStability annotation. </li> + * <li>Classes that are {@link Private} are to be considered unstable unless + * a different InterfaceStability annotation states otherwise.</li> + * <li>Incompatible changes must not be made to classes marked as stable.</li> + * </ul> + */ +@InterfaceAudience.User +@org.apache.hadoop.classification.InterfaceStability.Evolving +public class InterfaceStability { + /** + * Can evolve while retaining compatibility for minor release boundaries.; + * can break compatibility only at major release (ie. at m.0). + */ + @Documented + @Retention(RetentionPolicy.RUNTIME) + public @interface Stable { } + + /** + * Evolving, but can break compatibility at minor release (i.e. m.x) + */ + @Documented + @Retention(RetentionPolicy.RUNTIME) + public @interface Evolving { } + + /** + * No guarantee is provided as to reliability or stability across any + * level of release granularity. + */ + @Documented + @Retention(RetentionPolicy.RUNTIME) + public @interface Unstable { } +}