How to Deprecate APIs

Deprecating an API requires using two different mechanisms: the @Deprecated annotation and the @deprecated JavaDoc tag.

The @Deprecated annotation marks an API in a way that is recorded in the class file and is available at runtime. This allows various tools, such as javac and jdeprscan, to detect and flag usage of deprecated APIs. The @deprecated JavaDoc tag is used in documentation of deprecated APIs, for example, to describe the reason for deprecation, and to suggest alternative APIs.

Note the capitalization: the annotation starts with an uppercase D and the JavaDoc tag starts with a lowercase d.

Using the @Deprecated Annotation

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

• @Deprecated(since="<version>")

  • <version> identifies the version in which the API was deprecated. This is for informational purposes. The default is the empty string ("").

• @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)

The @Deprecated annotation causes the JavaDoc-generated documentation to be marked with one of the following, wherever that program element appears:

• Deprecated.

• Deprecated, for removal: This API element is subject to removal in a future version.

The javadoc tool generates a page named deprecated-list.html containing the list of deprecated APIs, and adds a link in the navigation bar to that page.

The following is a simple example of using the @Deprecated annotation from the java.lang.Thread class:

public class Thread implements Runnable {
	... 
	@Deprecated(since="1.2")
	public final void stop() {
		...
	}
	...

Semantics of Deprecation

The two elements of the @Deprecated annotation give developers the opportunity to clarify what deprecation means for their exported APIs (which are APIs that are provided by a library that are accessible to code outside of that library, such as applications or other libraries).

For the JDK platform:

• @Deprecated(forRemoval=true) indicates that the API is eligible to be removed in a future release of the JDK platform.

• @Deprecated(since="<version>") contains the JDK version string that indicates when the API element was deprecated, for those deprecated in JDK 9 and beyond.

If you maintain libraries and produce your own APIs, then you probably use the @Deprecated annotation. You should determine and communicate your policy around API removals. For example, if you release a new library every six weeks, then you may choose to deprecate an API for removal, but not remove it for several months to give your customers time to migrate.

Using the @deprecated JavaDoc Tag

Use the @deprecated tag in the JavaDoc comment of any deprecated program element to indicate that it should no longer be used (even though it may continue to work). This tag is valid in all class, method, or field documentation comments. The @deprecated tag must be followed by a space or a newline. In the paragraph following the @deprecated tag, explain why the item was deprecated, and suggest what to use instead. Mark the text that refers to new versions of the same functionality with an @link tag.

When it encounters an @deprecated tag, the javadoc tool moves the text following the @deprecated tag to the front of the description and precedes it with a warning. For example, this source:

  /**
   * ...
   * @deprecated  This method does not properly convert bytes into
   * characters.  As of JDK 1.1, the preferred way to do this is via the
   * {@code String} constructors that take a {@link
   * java.nio.charset.Charset}, charset name, or that use the platform's
   * default charset.
   * ...
   */
   @Deprecated(since="1.1")
   public String(byte ascii[], int hibyte) {
      ...

generates the following output:

@Deprecated(since="1.1")
public String​(byte[] ascii, 
              int hibyte)
Deprecated. This method does not properly convert bytes into characters. As of 
JDK 1.1, the preferred way to do this is via the String constructors that take a 
Charset, charset name, or that use the platform's default charset.

If you use the @deprecated JavaDoc tag without the corresponding @Deprecated annotation, a warning is generated.