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

[Stuart Marks]

Hi Ben,

No, -Xlint:-removal isn't completely silent. If you enable this option and 
compile a class that uses a terminally deprecated API, you get

     Note: UseSite.java uses or overrides a deprecated API that is marked for 
removal.
     Note: Recompile with -Xlint:removal for details.

This is a similar message to the one you get with ordinary deprecation warnings; 
you get a "Note:" if they're disabled. The main difference is that removal 
warnings are enabled by default.

In a sense, this "Note:" is a non-suppressible warning, but it doesn't cause a 
build with -Werror to fail. It's mainly there to satisfy the JLS 9.6.4.6 
requirement of there being some kind of warning when a deprecated API is used 
(even though the word "warning" isn't actually used in the message).

s'marks


On 11/1/16 11:42 PM, Ben Evans wrote:
> Hi Stuart,
>
> This seems to me the correct balance. One question I had is whether
> usage of the "-Xlint:-removal" flag is silent?
>
> I can see an argument that given the severity of this flag that a
> single, totally non-suppressible warning e.g. "WARNING: This
> invocation of javac has suppressed warnings about the forthcoming
> removal of heavily deprecated APIs" might be warranted at the start of
> the compilation run.
>
> Has this been considered? What was the conclusion about whether this
> was helpful?
>
> Thanks,
>
> Ben
>
> On Tue, Nov 1, 2016 at 10:54 PM, Stuart Marks <stuart.marks at oracle.com> wrote:
>> 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