Enhanced Deprecation
The semantics of what deprecation means has been clarified, including whether an API could also be removed within the near future.
If you're a library maintainer, you'll cash in of the updated deprecation syntax to tell users of your library about the status of APIs provided by your library.
If you're a library or application developer, you'll use the jdeprscan tool to seek out 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.
In the JDK, APIs are deprecated for widely varying reasons, such as:
The API is dangerous (for example, the Thread.stop method).
There is an easy rename (for example, AWT Component.show/hide replaced by setVisible).
A newer, better API can be used instead.
The deprecated API is going to be removed.
In prior releases, APIs were deprecated but virtually never removed. Starting with JDK 9, APIs could also be marked as deprecated for removal. This indicates that the API is eligible to be removed within the next release of the JDK platform. If your application or library consumes any of those APIs, then you ought to make an idea to migrate from them soon.
For an inventory of deprecated APIs within the current release of the JDK, see the Deprecated API page within the API specification.
How to Deprecate APIs
Deprecating an API requires using two different mechanisms: the @Deprecated inpidenc annotation and the @deprecated Javadoc tag.
The @Deprecated annotation marks an API during a way that's recorded within the class file and is out there at runtime. This allows various tools, like javac and jdeprscan, to detect and flag usage of deprecated APIs. The @deprecated Javadoc tag is employed in documentation of deprecated inpindc APIs, for instance , to explain the rationale for deprecation, and to suggest alternative APIs.
Note the capitalization: the annotation starts with an uppercase D and therefore the java 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> is the version when 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)
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 which contains 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.
@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 6 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 inpindec 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 altogether class, method, or field documentation comments. The @deprecated indpic tag must be followed by a space or a newline. In the paragraph following the @deprecated indinc tag, explain why the item was deprecated, and suggest what to use instead. Mark the text that refers to new versions of an equivalent 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:
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.
Notifications and Warnings
Suppressing inpdinc Deprecation Warnings
Notifications and Warnings
When an API is deprecated, developers must be notified. The deprecated API may cause problems in your code, or, if it's eventually removed, cause failures at run time.
The Java compiler generates warnings about deprecated APIs. There are options to get more information about warnings, and you'll 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 warning
Here 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 indmindec java files compiled during a particular ad run of javac. You may have identified specific locations in ASCII text file that generate warnings that you simply not want to ascertain . You can use the @SuppressWarnings annotation to suppress warnings whenever that code is compiled. Place the @SuppressWarnings annotation at the declaration of the category , method, field, or local variable that uses a deprecated API.
The @SuppressWarnings options are:
@SuppressWarnings("deprecation") — Suppresses only the ordinary deprecation warnings.
@SuppressWarnings("removal") — Suppresses only the removal warnings.
@SuppressWarnings({"deprecation","removal"}) — 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, albeit warnings are enabled on the instruction .
Running jdeprscan
jdeprscan may be a static analysis bast tool that reports on an application’s use of deprecated JDK API elements. Run jdeprscan to assist identify possible issues in compiled class java files or jar files.
You can determine abou 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 upon third-party libraries that are distributed as binary artifacts, then you should run jdeprscan.
It’s important to get dependencies on deprecated APIs before the APIs are faraway from the JDK. If the binary uses an new API that's deprecated for delete within the current JDK release, and you don’t recompile, then you won’t get any notifications. When the API is removed during a future JDK java release, then the binary will simply fail at runtime. jdeprscan allows you to detect such usage now, well before the API is delete file .
For the complete syntax of how to run the msol tool and how to interpret the output, see jdeprscan in the Java file Platform, Standard Edition Tools Reference.
It Usually Begins with javac
While you cannot overlook the very fact that the quality Java compiler javac from Sun includes tons of error checking that's mandated by the Java language, you'll easily miss the very fact that it's a bunch of additional checking that's yours for the asking. Simply add the command-line option -Xlint and you'll see variety of additional warnings. You can optionally append a comma-separated list of categories to the present option, as shown within the "javac Xlint options" table—for example, -Xlint:deprecation,unchecked will run the quality compiler with extra details on use of deprecated code and unchecked type conversions.
0 Comments: