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

[Ben Evans]

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