HADOOP-8059. Add javadoc to InterfaceAudience and InterfaceStability. Contributed by Brandon Li.
git-svn-id: https://svn.apache.org/repos/asf/hadoop/common/trunk@1354684 13f79535-47bb-0310-9956-ffa450edef68 (cherry picked from commit 24c4216bf0d75006fb218d743183f96658bea65c) Conflicts: hadoop-common-project/hadoop-common/CHANGES.txt Project: http://git-wip-us.apache.org/repos/asf/hadoop/repo Commit: http://git-wip-us.apache.org/repos/asf/hadoop/commit/3a783fe3 Tree: http://git-wip-us.apache.org/repos/asf/hadoop/tree/3a783fe3 Diff: http://git-wip-us.apache.org/repos/asf/hadoop/diff/3a783fe3 Branch: refs/heads/branch-2 Commit: 3a783fe38dd3520568ed2310ee8ea896fe44a109 Parents: d684b21 Author: Suresh Srinivas <[email protected]> Authored: Wed Jun 27 19:32:21 2012 +0000 Committer: cnauroth <[email protected]> Committed: Mon Mar 16 14:21:15 2015 -0700 ---------------------------------------------------------------------- .../hadoop/classification/InterfaceAudience.java | 18 ++++++++++++++++++ .../hadoop/classification/InterfaceStability.java | 13 ++++++++++++- hadoop-common-project/hadoop-common/CHANGES.txt | 3 +++ 3 files changed, 33 insertions(+), 1 deletion(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/hadoop/blob/3a783fe3/hadoop-common-project/hadoop-annotations/src/main/java/org/apache/hadoop/classification/InterfaceAudience.java ---------------------------------------------------------------------- diff --git a/hadoop-common-project/hadoop-annotations/src/main/java/org/apache/hadoop/classification/InterfaceAudience.java b/hadoop-common-project/hadoop-annotations/src/main/java/org/apache/hadoop/classification/InterfaceAudience.java index 98c506e..04d5511 100644 --- a/hadoop-common-project/hadoop-annotations/src/main/java/org/apache/hadoop/classification/InterfaceAudience.java +++ b/hadoop-common-project/hadoop-annotations/src/main/java/org/apache/hadoop/classification/InterfaceAudience.java @@ -23,6 +23,24 @@ import java.lang.annotation.RetentionPolicy; /** * Annotation to inform users of a package, class or method's intended audience. + * Currently the audience can be {@link Public}, {@link LimitedPrivate} or + * {@link Private}. <br> + * All public classes must have InterfaceAudience annotation. <br> + * <ul> + * <li>Public classes that are not marked with this annotation must be + * considered by default as {@link Private}.</li> + * + * <li>External applications must only use classes that are marked + * {@link Public}. Avoid using non public classes as these classes + * could be removed or change in incompatible ways.</li> + * + * <li>Hadoop projects must only use classes that are marked + * {@link LimitedPrivate} or {@link Public}</li> + * + * <li> 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 Public}, but a method may be {@link LimitedPrivate} + * </li></ul> */ @InterfaceAudience.Public @InterfaceStability.Evolving http://git-wip-us.apache.org/repos/asf/hadoop/blob/3a783fe3/hadoop-common-project/hadoop-annotations/src/main/java/org/apache/hadoop/classification/InterfaceStability.java ---------------------------------------------------------------------- diff --git a/hadoop-common-project/hadoop-annotations/src/main/java/org/apache/hadoop/classification/InterfaceStability.java b/hadoop-common-project/hadoop-annotations/src/main/java/org/apache/hadoop/classification/InterfaceStability.java index 8454553..fbcac0d 100644 --- a/hadoop-common-project/hadoop-annotations/src/main/java/org/apache/hadoop/classification/InterfaceStability.java +++ b/hadoop-common-project/hadoop-annotations/src/main/java/org/apache/hadoop/classification/InterfaceStability.java @@ -21,9 +21,20 @@ import java.lang.annotation.Documented; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; +import org.apache.hadoop.classification.InterfaceAudience.LimitedPrivate; +import org.apache.hadoop.classification.InterfaceAudience.Private; +import org.apache.hadoop.classification.InterfaceAudience.Public; + /** * Annotation to inform users of how much to rely on a particular package, - * class or method not changing over time. + * class or method not changing over time. Currently the stability can be + * {@link Stable}, {@link Evolving} or {@link Unstable}. <br> + * + * <ul><li>All classes that are annotated with {@link Public} or + * {@link LimitedPrivate} 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> */ @InterfaceAudience.Public @InterfaceStability.Evolving http://git-wip-us.apache.org/repos/asf/hadoop/blob/3a783fe3/hadoop-common-project/hadoop-common/CHANGES.txt ---------------------------------------------------------------------- diff --git a/hadoop-common-project/hadoop-common/CHANGES.txt b/hadoop-common-project/hadoop-common/CHANGES.txt index f6f535f..a1d2125 100644 --- a/hadoop-common-project/hadoop-common/CHANGES.txt +++ b/hadoop-common-project/hadoop-common/CHANGES.txt @@ -262,6 +262,9 @@ Release 2.7.0 - UNRELEASED HADOOP-11714. Add more trace log4j messages to SpanReceiverHost (cmccabe) + HADOOP-8059. Add javadoc to InterfaceAudience and InterfaceStability. + (Brandon Li via suresh) + OPTIMIZATIONS HADOOP-11323. WritableComparator#compare keeps reference to byte array.
