Bug 59804

Summary: Add annotation for indicating when deprecated features may be removed
Product: POI Reporter: Javen O'Neal <onealj>
Component: POI OverallAssignee: POI Developers List <dev>
Status: NEW ---    
Severity: enhancement CC: dtn-asfbugs
Priority: P2    
Version: 3.15-dev   
Target Milestone: ---   
Hardware: PC   
OS: All   
Attachments: Find @Deprecated and @Removal annotations with reflection

Description Javen O'Neal 2016-07-05 21:50:58 UTC 
As part of managing binary and source backwards compatibility, we have @Internal, @Deprecated (and @deprecated javadoc), annotations.
We usually keep deprecated features around for at least 2 final releases before removing, but sometimes never get around to removing the deprecated features.
This bug will try to better track the revisit of deprecated elements.

From David North on the dev mailing list [1]:
> * Use the @Deprecated annotation in addition to the JavaDoc tag (which
> is useful for some IDEs anyway)
> * Invent our own @Removal annotation to contain the date/POI version of
> expected removal 
> 
> Then it would be easy to write a functional test which used reflection
> to check all @Deprecated annotated elements had an @Removal too, and to
> tell us when things come up as due to be removed. 

Related: [2] finding the version when a feature was deprecated

[1] http://apache-poi.1045710.n5.nabble.com/deprecated-handling-reloaded-tp5721071p5721078.html
[2] http://apache-poi.1045710.n5.nabble.com/Finding-deprecated-methods-td5723416.html
Comment 1 Javen O'Neal 2016-07-05 23:27:54 UTC 
Added @Removal annotation class in r1751569.

Usage:

/**
 * @since POI 3.6
 * @deprecated POI 3.15 beta 3
 */
@Removal(version="3.17")
public class SomeDeprecatedClassOrMethod() { }
Comment 2 Javen O'Neal 2016-08-03 00:34:08 UTC 
Todo: write code that uses reflection to find code that is overdue for removal, and build this into a unit test.
Comment 3 Javen O'Neal 2017-02-20 10:57:49 UTC 
Created attachment 34767 [details]
Find @Deprecated and @Removal annotations with reflection

The ClassFinder class in the patch uses non-free code. Do we have something already in POI test scaffolding that could give us a list of every org.apache.poi class (bonus points if it can include the o.a.p junit test code)?

If not, is there an ASL-2.0-licensed version that does something similar? Otherwise, we'll need to rewrite these couple lines of recursive class finding via reflection from scratch.
Comment 4 Nick Burch 2017-02-20 10:59:25 UTC 
Doesn't the OOXMLLite code do something much like that only for the schema classes?
Comment 5 Javen O'Neal 2017-02-20 11:24:17 UTC 
(In reply to Nick Burch from comment #4)
> Doesn't the OOXMLLite code do something much like that only for the schema
> classes?

Probably. The JDK, IDE, and JUnit also find all classes through recursive reflection, if OOXMLLite doesn't pan out.