Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8231411

Improve javac messages for using a preview API

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P3
    • Resolution: Approved
    • Fix Version/s: 14
    • Component/s: tools
    • Labels:
      None
    • Subcomponent:
    • Compatibility Kind:
      source, behavioral
    • Compatibility Risk:
      minimal
    • Interface Kind:
      Java API, Language construct

      Description

      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.)

      API type
      --enable-preview
      No Suppression
      --enable-preview
      Suppression
      No --enable-preview
      No Suppression
      No --enable-preview
      Suppression
      essential mandatory warning no warning error error
      non-essential mandatory warning no warning mandatory warning no warning

      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.

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                jlahoda Jan Lahoda
                Reporter:
                darcy Joe Darcy
                Reviewed By:
                Maurizio Cimadamore
              • Votes:
                0 Vote for this issue
                Watchers:
                6 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: