Enhanced Deprecation in Java 9

JEP 277: Enhanced Deprecation

The main goal of this JEP(JDK Enhancement Proposal) is to revamp the @Deprecated annotation, and provide tools to strengthen the API life cycle. It intends to provide better information about the status and intended disposition of APIs in the specification

---

Deprecation is a notification to library consumers that they should migrate code from a deprecated API. Deprecation is a technique to communicate information about the life cycle of an API: to encourage applications to migrate away from the API, to discourage applications from forming new dependencies on the API, and to inform developers of the risks of continuing dependence upon the API.

APIs have been deprecated for widely varying reasons, such as:

• The API is dangerous.
• There is a simple rename.
• A newer, better API can be used instead.

Java offers two mechanisms to express deprecation:

• the @deprecated Javadoc tag, introduced in JDK 1.1,
• the @Deprecated annotation, introduced in Java SE 5.

A program element annotated @Deprecated is one that programmers are discouraged from using, typically because it is dangerous, or because a better alternative exists. Compilers warn when a deprecated program element is used or overridden in non-deprecated code.

However,very few deprecated APIs were actually removed, leading some people to believe that nothing would ever be removed. On the other hand, other people believed that everything that was deprecated might eventually be removed, which was never the intent either. This resulted in an unclear message being delivered to developers about the meaning of @Deprecated.

Starting with JDK 9, APIs may be marked as deprecated for removal. This indicates that the API is eligible to be removed in the next release of the JDK platform. If your application or library consumes any of these APIs, then you should make a plan to migrate from them soon.

Using the @Deprecated Annotation

To indicate deprecation, precede the module, class, method, or member declaration with @Deprecated. The annotation contains these elements:

• string-valued element since

  The value of this element indicates the version in which the annotated program element was first deprecated.

  @Deprecated(since="<version>")

  • <version> is the version when the API was deprecated. This is for informational purposes. The default is the empty string ("").
• boolean-valued element forRemoval

  A value of true indicates intent to remove the annotated program element in a future version. A value of false indicates that use of the annotated program element is discouraged, but at the time the program element was annotated, there was no specific intent to remove it.

  @Deprecated(forRemoval=<boolean>)

  • forRemoval=true indicates that the API is subject to removal in a future release.
  • forRemoval=false recommends that code should no longer use this API; however, there is no current intent to remove the API. This is the default value.

For example:

@Deprecated(since="9", forRemoval=true)

Indicates that the API is deprecated in JDK9 and beyond and is eligible to be removed in a future release of the JDK platform.

Note:

• There is no defined order among annotation elements. As a matter of style, the since element should be placed first.
• It is strongly recommended that the reason for deprecating a program element be explained in the documentation, using the @deprecated javadoc tag. The documentation should also suggest and link to a recommended replacement API, if applicable. A replacement API often has subtly different semantics, so such issues should be discussed as well.
• The @Deprecated annotation should always be present if the @deprecated javadoc tag is present, and vice-versa.