bug 59804: add since attribute to @Internal annotation; add @Removal annotation to track when features will be removed

git-svn-id: https://svn.apache.org/repos/asf/poi/trunk@1751569 13f79535-47bb-0310-9956-ffa450edef68

src/java/org/apache/poi/util/Internal.java

@@ -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
@@ -35,4 +41,12 @@ import java.lang.annotation.Documented;
 @Retention(RetentionPolicy.RUNTIME)
 public @interface Internal {
     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 "";
 }

src/java/org/apache/poi/util/Removal.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.poi.util;
+
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Retention;
+import java.lang.annotation.Documented;
+
+
+/**
+ * <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>
+ *
+ * <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 Removal {
+    /**
+     * The POI version when this feature may be removed.
+     *
+     * Format: "(?<major>\d+)\.(?<minor>\d+)"
+     * Example: "3.15"
+     */
+    String version() default "";
+}