svn commit: r1751569 - in /poi/trunk/src/java/org/apache/poi/util: Internal.java Removal.java

[on...@apache.org]

Author: onealj
Date: Tue Jul  5 23:01:05 2016
New Revision: 1751569

URL: http://svn.apache.org/viewvc?rev=1751569&view=rev
Log:
bug 59804: add since attribute to @Internal annotation; add @Removal annotation to track when features will be removed

Added:
    poi/trunk/src/java/org/apache/poi/util/Removal.java
      - copied, changed from r1751553, poi/trunk/src/java/org/apache/poi/util/Internal.java
Modified:
    poi/trunk/src/java/org/apache/poi/util/Internal.java

Modified: poi/trunk/src/java/org/apache/poi/util/Internal.java
URL: http://svn.apache.org/viewvc/poi/trunk/src/java/org/apache/poi/util/Internal.java?rev=1751569&r1=1751568&r2=1751569&view=diff
==============================================================================
--- poi/trunk/src/java/org/apache/poi/util/Internal.java (original)
+++ poi/trunk/src/java/org/apache/poi/util/Internal.java Tue Jul  5 23:01:05 2016
@@ -24,9 +24,15 @@ import java.lang.annotation.Documented;
 
 /**
  * Program elements annotated @Internal are intended for
- * POI internal use only. Such elements are not public by design
- * and likely to be removed in future versions of POI  or access
- * to such elements will be changed from 'public' to 'default' or less.
+ * POI internal use only.
+ *
+ * Such elements are not public by design and likely to be removed, have their
+ * signature change, or have their access level decreased from public to
+ * protected, package, or private in future versions of POI without notice.
+ *
+ * @Internal elements are eligible for immediate modification or removal and are
+ * not subject to the POI project policy of deprecating an element for 2 major
+ * releases before removing.
  *
  * @author Yegor Kozlov
  * @since POI-3.6
@@ -34,5 +40,13 @@ import java.lang.annotation.Documented;
 @Documented
 @Retention(RetentionPolicy.RUNTIME)
 public @interface Internal {
-    String value() default "";    
+    String value() default "";
+    /**
+     * The POI version when an element was declared internal.
+     * This is not the same as an @since javadoc annotation
+     * which specifies when the feature itself was added.
+     * A feature that was made internal after it was added may
+     * have a different since and Internal-since version numbers.
+     * */
+    String since() default "";
 }

Copied: poi/trunk/src/java/org/apache/poi/util/Removal.java (from r1751553, poi/trunk/src/java/org/apache/poi/util/Internal.java)
URL: http://svn.apache.org/viewvc/poi/trunk/src/java/org/apache/poi/util/Removal.java?p2=poi/trunk/src/java/org/apache/poi/util/Removal.java&p1=poi/trunk/src/java/org/apache/poi/util/Internal.java&r1=1751553&r2=1751569&rev=1751569&view=diff
==============================================================================
--- poi/trunk/src/java/org/apache/poi/util/Internal.java (original)
+++ poi/trunk/src/java/org/apache/poi/util/Removal.java Tue Jul  5 23:01:05 2016
@@ -23,16 +23,36 @@ import java.lang.annotation.Documented;
 
 
 /**
- * Program elements annotated @Internal are intended for
- * POI internal use only. Such elements are not public by design
- * and likely to be removed in future versions of POI  or access
- * to such elements will be changed from 'public' to 'default' or less.
+ * <p>Program elements annotated &#64;Removal track the earliest final release
+ * when a deprecated feature will be removed. This is an internal decoration:
+ * a feature may be removed in a release earlier or later than the release
+ * number specified by this annotation.</p>
  *
- * @author Yegor Kozlov
- * @since POI-3.6
+ * <p>The POI project policy is to deprecate an element for 2 final releases
+ * before removing. This annotation exists to make it easier to follow up on the
+ * second step of the two-step deprecate and remove process.</p>
+ *
+ * <p>A deprecated feature may be removed in nightly and beta releases prior
+ * to the final release for which it is eligible, but may be removed later for
+ * various reasons. If it is known in advance that the feature will not be
+ * removed in the n+2 release, a later version should be specified by this
+ * annotation. The annotation version number should not include beta</p>
+ *
+ * <p>For example, a feature with a <code>&#64;deprecated POI 3.15 beta 3</code>
+ * is deprecated in POI 3.15 and 3.16 and becomes eligible for deletion during
+ * the POI 3.17 release series, and may be deleted immediately after POI 3.16 is
+ * released. This would be annotated <code>&#64;Removal(version="3.17")</p>.
+ * 
+ * @since POI-3.15 beta 3
  */
 @Documented
 @Retention(RetentionPolicy.RUNTIME)
-public @interface Internal {
-    String value() default "";    
+public @interface Removal {
+    /**
+     * The POI version when this feature may be removed.
+     *
+     * Format: "(?<major>\d+)\.(?<minor>\d+)"
+     * Example: "3.15"
+     */
+    String version() default "";
 }



---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@poi.apache.org
For additional commands, e-mail: commits-help@poi.apache.org