moparisthebest/poi
1
0
Fork 0
Code Issues Pull Requests Releases 1 Wiki Activity

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

Browse Source 
git-svn-id: https://svn.apache.org/repos/asf/poi/trunk@1751569 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Javen O'Neal 2016-07-05 23:01:05 +00:00
parent 05cecde4a5
commit f78b266d73
2 changed files with 76 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
src/java/org/apache/poi/util/Internal.java
View File

@ -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 "";
}

58
src/java/org/apache/poi/util/Removal.java Normal file
View 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 &#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 "";
}