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
This commit is contained in:
parent
05cecde4a5
commit
f78b266d73
@ -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 "";
|
||||
}
|
||||
|
58
src/java/org/apache/poi/util/Removal.java
Normal file
58
src/java/org/apache/poi/util/Removal.java
Normal file
@ -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 @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>@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>@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 "";
|
||||
}
|
Loading…
Reference in New Issue
Block a user