Improve javac messages for using an API associated with a preview feature

Summary

Any API associated with a preview feature will receive special handling in javac and javadoc.

Problem

In JDK 12 and 13, an API associated with a preview feature is annotated as deprecated for removal as soon as the API is introduced. For example, String::stripIndent is deprecated for removal in JDK 13 because it is associated with text blocks (JEP 355), a preview feature of JDK 13. The intent is to un-deprecate the API in a future JDK if the preview feature graduates into a final and permanent feature. However, using deprecation in this manner is problematic for at least two reasons: 1) Use of the API leads to a deprecation warning, but the warning does not communicate anything about the "connection" to a preview feature, leading to usability issues and confusion; 2) It is difficult to find/keep track of the APIs introduced for particular preview features.

Solution

When an API element is added to support a preview feature, the API element will be marked as either a) "essential", if it appears in an ordinary, non-reflective API of Java SE, such as in a class in the java.lang package, or b) "non-essential", if it appears either in a reflective API of Java SE, such as in a class of java.lang.reflect or javax.lang.model, or in a JDK-specific API, such as in a class of the Trees API. Depending on the classification, any use of the marked element will get special handling in javac and javadoc.

Specification

Whenever use of a marked API element is detected, javac behaves as follows.

("Suppression" means @SuppressWarnings("preview") applies in the developer's program to the point where the marked API element is used/invoked/overridden.)

--enable-preview

No Suppression

--enable-preview

Suppression

No --enable-preview

No Suppression

No --enable-preview

Suppression

Note the bold text: when preview features are disabled, it is a compile-error to use an essential API element. The API element is available for use only when its "sponsoring" preview feature is enabled.

The precise output of javac for a "mandatory warning" is as follows:

• with -Xlint:preview, a warning on each occurrence.
• with -Xlint:-preview, a summary at the end of the compilation stating preview features have been used.

The default is -Xlint:preview when no --enable-preview is present, and -Xlint:-preview when --enable-preview is present. An explicit -Xlint setting overrides this default.

The list of essential Java SE APIs will be given in the JLS.

javadoc will contain a helpful text on all APIs related to preview features.

Marking an API element in support a preview feature does not represent a commitment to keep the API element in Java SE or the JDK beyond the lifetime of the preview feature. We reserve the right to remove any API that is so marked at any time.

The following specific API changes are also included:

In java.lang.String, the methods

• formatted(java.lang.Object...)
• stripIndent()
• translateEscapes()

Analogous changes are made in the com.sun.source tree API for the switch expression features.

See details in the attached specdiff. have their @Deprecated annotations removed and replaced with a preview feature warning.