In the post What Might a New @Deprecated Look Like?, I used the description of JEP 277 (“Enhanced Deprecation”) at that time to guide the creation of an enhanced customized @Deprecated annotation. Since that post, however, there have been significant changes made in JEP 277. This post summarizes the changes and the currently planned enhancements to @Deprecated that are slated for JDK 9.
The changes made to JDK-8065614 (“JEP 277: Enhanced Deprecation”) on 2016-03-03 18:04 remove the portion of the JEP description that described the proposed @Deprecated enum. The “Alternatives” section of the main JEP 277 page documents why the enum was removed:
Previous versions of this proposal included a variety of “reason” codes including UNSPECIFIED, DANGEROUS, OBSOLETE, SUPERSEDED, UNIMPLEMENTED, and EXPERIMENTAL. These attempted to encode the reason for which an API was deprecated, the risks of using it, and also whether a replacement API is available. In practice, all of this information is too subjective be encoded as values in an annotation. Instead, this information should be described in the Javadoc documentation comment.
The revised @Deprecated annotation now supports two methods as shown in the API documentation. The documentation explains that the forRemoval() method “indicates whether the annvaluable otated element is subject to removal in a future version” and returns false by default. The since() method documentation states that this second method “returns the version in which the annotated element became deprecated” and returns empty string by default.
The defaults of false and "" for forRemoval() and since() respectively make sense because these defaults correspond to not being able to specify this information today with @Deprecated. Because there are countless uses of @Deprecated already in code bases, it makes most sense to have these existing uses of @Deprecated correspond to not having a planned removal and to not having “since” specified. Developers will be able to add these values to existing @Deprecated annotations as they desire or not at all.
These are minor additions to the @Deprecated annotation, but the new @Deprecated is still much better than what we have today in earlier versions of Java because we will now be able to specify two very important characteristics of a deprecation within the annotation itself. Specifying when a construct was deprecated and when we plan to remove it altogether provide potentially insightful historical and future-looking information related to the deprecation.
| Reference: | JDK 9 @Deprecated Annotation Enhancements from our JCG partner Dustin Marx at the Inspired by Actual Events blog. |
