diff --git a/src/java/org/apache/poi/util/Internal.java b/src/java/org/apache/poi/util/Internal.java index 2177e09dd2..565a908d7b 100644 --- a/src/java/org/apache/poi/util/Internal.java +++ b/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 @@ -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 ""; } diff --git a/src/java/org/apache/poi/util/Removal.java b/src/java/org/apache/poi/util/Removal.java new file mode 100644 index 0000000000..75d0dabdcd --- /dev/null +++ b/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; + + +/** + *
Program elements annotated @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.
+ * + *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.
+ * + *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
+ * + *For example, a feature with a @deprecated POI 3.15 beta 3
+ * 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 @Removal(version="3.17")