Deprecation warnings changes in jdk9+142 -- removal warnings enabled by default

[Stuart Marks]

Hi all,

Thanks to some work by Jon Gibbons, javac's warnings behavior in JDK 9 build 142 
[1] has been enhanced to deal with terminal deprecations (deprecations with 
forRemoval=true). I've updated the JEP 277 text [2] to clarify and explain the 
expected behavior.

Warnings at use sites of terminally deprecated APIs are now enabled by default, 
and are considered to be a different kind of warning -- a "removal" warning -- 
from the ordinary deprecation warnings that have been issued up until now. They 
aren't suppressed by @SuppressWarnings("deprecation"). Instead, they can be 
suppressed with @SuppressWarnings("removal").

(It's also possible to disable the "removal" lint category through a command 
line option -Xlint:-removal. I recommend avoiding this option, unless you're 
willing to be surprised by the removal of APIs.)

The javac warnings change, along with terminal deprecations appearing in JDK 9, 
can cause warnings to occur even at sites where they had been suppressed. This 
could be viewed as an incompatibility, though this change was deliberate.

Consider a case where some code uses a deprecated API, and this code was 
annotated with @SuppressWarnings("deprecation") in order for the compilation to 
be warnings-free. Suppose the API's deprecation is then "upgraded" to have 
forRemoval=true. We want the new removal warning to bypass the previous warnings 
suppression, since this is the last chance before the API is actually removed. 
If this weren't done, an API might be deprecated for removal, and then removed, 
without any additional warnings being emitted.

This is quite likely to occur with JDK 9, as it deprecates several APIs for 
removal that had previously been deprecated for many years. Use sites of such 
APIs probably have had warnings suppressed. It seems prudent to offer one final 
round of warnings to users before these APIs are actually removed.

Here's an example of javac's new warnings. Consider the following files:

::::: DeclSite.java :::::

public class DeclSite {
     @Deprecated public static void ordinary() { }
     @Deprecated(forRemoval=true) public static void removal() { }
}

::::: UseSite.java :::::

public class UseSite {
     void foo() {
         DeclSite.ordinary();
         DeclSite.removal();
     }
}

Compiling these files with javac from jdk9+142 produces the following:

:::::
UseSite.java:4: warning: [removal] removal() in DeclSite has been deprecated and 
marked for removal
         DeclSite.removal();
                 ^
Note: UseSite.java uses or overrides a deprecated API.
Note: Recompile with -Xlint:deprecation for details.
1 warning
:::::

s'marks


[1] https://jdk9.java.net/download/
[2] http://openjdk.java.net/jeps/277