Bug 59804 - Add annotation for indicating when deprecated features may be removed
Summary: Add annotation for indicating when deprecated features may be removed
Status: NEW
Alias: None
Product: POI
Classification: Unclassified
Component: POI Overall (show other bugs)
Version: 3.15-dev
Hardware: PC All
: P2 enhancement (vote)
Target Milestone: ---
Assignee: POI Developers List
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2016-07-05 21:50 UTC by Javen O'Neal
Modified: 2017-02-20 11:31 UTC (History)
1 user (show)



Attachments
Find @Deprecated and @Removal annotations with reflection (11.72 KB, patch)
2017-02-20 10:57 UTC, Javen O'Neal
Details | Diff

Note You need to log in before you can comment on or make changes to this bug.
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.