Oracle proposal clarifies Java API deprecations
Identified as JDK Enhancement Proposal (JEP): 277 Enhanced Deprecation, the plan from Oracle's Stuart Marks would revamp the deprecation annotation and offer tools to boost the tail end of the feature lifecycle. It calls for providing better information about the status and intended disposition of APIs, and for enhancing the runtime to emit warnings so that an application's dynamic usage of deprecated APIs can be logged. A tool would be provided to generate static information about this usage.
Deprecation of APIs recently became a hot-button issue when Oracle proposed making private APIs inaccessible in Java 9. Oracle then backed off a bit and decided to leave a few of them, including the popular sun.misc.Unsafe API, accessible. "The deprecation mechanism of Java SE needs to be revamped. It has been applied inconsistently, and there is confusion about its meaning and its proper use," the proposal states.
Intended for implementation in Java Standard Edition 9, which is due next fall, the proposal also intends to clarify policies of Java SE and the JDK with regard to the feature lifecycle. This includes requirements around annotating features as deprecated and the amount of notice to be given before a feature is removed. "This should allow defunct features to be removed in a more timely fashion," the proposal states.
Java has had a deprecation annotation, but it was not all that effective. "Very few deprecated APIs were actually removed," according to the proposal, "leading people to believe that nothing would ever be removed. On the other hand, there was confusion because other people believed that anything deprecated might eventually be removed, which was never the intent either." Developers thus ended up with an unclear message about the meaning of "deprecated" and what to do when encountering usage of a deprecated API.
"As APIs become deprecated in successive versions of the JDK, existing binaries continue to depend and use the deprecated APIs with no warnings," the proposal says. "If a deprecated API were to be removed in a JDK release, even after one or more releases where it was deprecated, this would come as an unpleasant surprise to users of old application binaries." The application would fail with a linkage error, without warning.
"Worse, there is no means for developers to check whether existing binaries have any dependencies on deprecated APIs," JEP 277 states. "This causes significant tension between binary compatibility and the need to evolve the specification through the retirement of old APIs."
JEP 277 was first created last year and updated in late October; the proposal was recently announced during a presentation at the recent JavaOne conference.