Annotation Interface Deprecated
A program element annotated @Deprecated is one that programmers are discouraged from using. An element may be deprecated for any of several reasons, for example, its usage is likely to lead to errors; it may be changed incompatibly or removed in a future version; it has been superseded by a newer, usually preferable alternative; or it is obsolete.
Compilers issue warnings when a deprecated program element is used or overridden in non-deprecated code. Use of the @Deprecated annotation on a local variable declaration or on a parameter declaration or a package declaration has no effect on the warnings issued by a compiler.
When a module is deprecated, the use of that module in requires , but not in exports or opens clauses causes a warning to be issued. A module being deprecated does not cause warnings to be issued for uses of types within the module.
This annotation type has a string-valued element since . The value of this element indicates the version in which the annotated program element was first deprecated.
This annotation type has a 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.
API Note: 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.
It is recommended that a since value be provided with all newly annotated program elements. Note that since cannot be mandatory, as there are many existing annotations that lack this element value.
There is no defined order among annotation elements. As a matter of style, the since element should be placed first.
The @Deprecated annotation should always be present if the @deprecated javadoc tag is present, and vice-versa.
Java mark as deprecated
The semantics of what deprecation means includes whether an API may be removed in the near future.
If you are a library maintainer, you can take advantage of the updated deprecation syntax to inform users of your library about the status of APIs provided by your library.
If you are a library or application developer, you can use the jdeprscan tool to find uses of deprecated JDK API elements in your applications or libraries.
Deprecation in the JDK
Deprecation is a notification to library consumers that they should migrate code from a deprecated API.
- The API is dangerous (for example, the Thread.stop method).
- There is a simple rename (for example, AWT Component.show/hide replaced by setVisible ).
- A newer, better API can be used instead.
- The API is going to be removed.
In prior releases, APIs were deprecated but rarely ever removed. 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 plan to migrate from them soon.
For a list of deprecated APIs in the current release of the JDK, see the Deprecated API page in the API specification.
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 codeph»>»)
- identifies the version in which the API was deprecated. This is for informational purposes. The default is the empty string ( » » ).
- 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)
- 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() < . >.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).
- @Deprecated(forRemoval=true) indicates that the API is eligible to be removed in a future release of the JDK platform.
- @Deprecated(since codeph»>») 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 * constructors that take a , 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.
Notifications and Warnings
When an API is deprecated, developers must be notified. The deprecated API may cause problems in your code, or, if it is eventually removed, cause failures at run time.
The Java compiler generates warnings about deprecated APIs. There are options to generate more information about warnings, and you can also suppress deprecation warnings.
Compiler Deprecation Warnings
If the deprecation is forRemoval=false , the Java compiler generates an "ordinary deprecation warning" . If the deprecation is forRemoval=true , the compiler generates a "removal warning" .
The two kinds of warnings are controlled by separate -Xlint flags: -Xlint:deprecation and -Xlint:removal . The javac -Xlint:removal option is enabled by default, so removal warnings are shown.
The warnings can also be turned off independently (note the "–" ): -Xlint:-deprecation and -Xlint:-removal .
This is an example of an ordinary deprecation warning.
$ javac src/example/DeprecationExample.java Note: src/example/DeprecationExample.java uses or overrides a deprecated API. Note: Recompile with -Xlint:deprecation for details.Use the javac -Xlint:deprecation option to see what API is deprecated.
$ javac -Xlint:deprecation src/example/DeprecationExample.java src/example/DeprecationExample.java:12: warning: [deprecation] getSelectedValues() in JList has been deprecated Object[] values = jlist.getSelectedValues(); ^ 1 warningHere is an example of a removal warning.
public class RemovalExample < public static void main(String[] args) < System.runFinalizersOnExit(true); >> $ javac RemovalExample.java RemovalExample.java:3: warning: [removal] runFinalizersOnExit(boolean) in System has been deprecated and marked for removal System.runFinalizersOnExit(true); ^ 1 warning ==========Suppressing Deprecation Warnings
The javac -Xlint options control warnings for all files compiled in a particular run of javac . You may have identified specific locations in source code that generate warnings that you no longer want to see. You can use the @SuppressWarnings annotation to suppress warnings whenever that code is compiled. Place the @SuppressWarnings annotation at the declaration of the class, method, field, or local variable that uses a deprecated API.
- @SuppressWarnings("deprecation") — Suppresses only the ordinary deprecation warnings.
- @SuppressWarnings("removal") — Suppresses only the removal warnings.
- @SuppressWarnings() — Suppresses both types of warnings.
Here’s an example of suppressing a warning.
@SuppressWarnings("deprecation") Object[] values = jlist.getSelectedValues();With the @SuppressWarnings annotation, no warnings are issued for this line, even if warnings are enabled on the command line.
Running jdeprscan
jdeprscan is a static analysis tool that reports on an application’s use of deprecated JDK API elements. Run jdeprscan to help identify possible issues in compiled class files or jar files.
You can find out about deprecated JDK APIs from the compiler notifications. However, if you don’t recompile with every JDK release, or if the warnings were suppressed, or if you depend on third-party libraries that are distributed as binary artifacts, then you should run jdeprscan .
It’s important to discover dependencies on deprecated APIs before the APIs are removed from the JDK. If the binary uses an API that is deprecated for removal in the current JDK release, and you don’t recompile, then you won’t get any notifications. When the API is removed in a future JDK release, then the binary will simply fail at runtime. jdeprscan lets you detect such usage now, well before the API is removed.
For the complete syntax of how to run the tool and how to interpret the output, see The jdeprscan Command in the Java Development Kit Tool Specifications .