Details
-
Enhancement
-
Resolution: Fixed
-
P4
-
15
Description
After JLS 13 introduced the idea of preview features in the Java language, JLS 14 introduced the idea that "A preview feature may be associated with elements of the Java SE Platform API. Namely, an API element is _essential_ if it exists in the package java.lang or java.lang.annotation, and programs cannot use the preview feature without referring (directly or indirectly) to the API element."
Going forward, a Java SE release will have preview APIs that may or may not have any association with the Java language (neither with preview language features nor permanent language features). Per JEP 12, the taxonomy of preview APIs is "essential", "reflective", "convenient", and "standalone". JLS 1.5 should say that any use of a preview API (except for a reflective one) causes an error (respectively, a warning) if preview features are disabled (respectively, enabled). In more detail:
-----
A *preview feature* is:
- a new feature of the Java language ("preview language feature"), or
- a new module, package, class, method, constructor, field, or enum constant in the `java.*` or `javax.*` namespace ("preview API")
that is fully specified, fully implemented, and yet impermanent. It is available in implementations of a given release of the Java SE Platform to provoke developer feedback based on real world use; this may lead to it becoming permanent in a future release of the Java SE Platform.
Implementations must disable, at both compile time and run time, the preview features defined by a given release of the Java SE Platform, unless the user indicates via the host system, at both compile time and run time, that preview features are to be enabled.
The preview language features defined by a given release of the Java SE Platform are specified in standalone documents that indicate changes ("diffs") to The Java® Language Specification for that release. The specifications of preview language features are incorporated into The Java® Language Specification by reference, and made a part thereof, if and only if preview features are enabled at compile time.
The preview APIs defined by a given release of the Java SE Platform are listed in the Java SE Platform Specification and specified in the Java SE API Specification.
Some preview APIs are described as _reflective_ by the Java SE Platform Specification, principally the java.lang.{reflect,invoke} and javax.{lang.model,annotation,tools} packages. The rule for use of reflective preview APIs is as follows:
- Whether preview features are enabled or disabled, a Java compiler must produce a _preview warning_ if a reflective preview API element is used (overridden, invoked, or referenced by name) in the declaration of a program element (whether explicitly or implicitly declared), unless:
The declaration where the use of a reflective preview API element appears is within the same module as the declaration of the reflective preview API element; or
The use is within a declaration that is annotated to suppress preview warnings (§9.6.4.5); or
The use is within an import declaration that imports the preview API element.
For all other preview APIs in the Java SE Platform Specification, the rules for use are as follows:
- If preview features are disabled, then a compile-time error occurs if either (i) a preview API element, or (ii) a type declared using a preview language feature, is used (overridden, invoked, or referenced by name) in the declaration of a program element (whether explicitly or implicitly declared), unless:
The declaration where the use of a preview API element appears is within the same module as the declaration of the preview API element.
- If preview features are enabled, then a Java compiler must produce a _preview warning_ if either (i) a preview API element, or (ii) a type declared using a preview language feature, is used (overridden, invoked, or referenced by name) in the declaration of a program element (whether explicitly or implicitly declared), unless:
The declaration where the use of a preview API element appears is within the same module as the declaration of the preview API element; or
The use is within a declaration that is annotated to suppress preview warnings (§9.6.4.5); or
The use is within an import declaration that imports the preview API element.
-----
Going forward, a Java SE release will have preview APIs that may or may not have any association with the Java language (neither with preview language features nor permanent language features). Per JEP 12, the taxonomy of preview APIs is "essential", "reflective", "convenient", and "standalone". JLS 1.5 should say that any use of a preview API (except for a reflective one) causes an error (respectively, a warning) if preview features are disabled (respectively, enabled). In more detail:
-----
A *preview feature* is:
- a new feature of the Java language ("preview language feature"), or
- a new module, package, class, method, constructor, field, or enum constant in the `java.*` or `javax.*` namespace ("preview API")
that is fully specified, fully implemented, and yet impermanent. It is available in implementations of a given release of the Java SE Platform to provoke developer feedback based on real world use; this may lead to it becoming permanent in a future release of the Java SE Platform.
Implementations must disable, at both compile time and run time, the preview features defined by a given release of the Java SE Platform, unless the user indicates via the host system, at both compile time and run time, that preview features are to be enabled.
The preview language features defined by a given release of the Java SE Platform are specified in standalone documents that indicate changes ("diffs") to The Java® Language Specification for that release. The specifications of preview language features are incorporated into The Java® Language Specification by reference, and made a part thereof, if and only if preview features are enabled at compile time.
The preview APIs defined by a given release of the Java SE Platform are listed in the Java SE Platform Specification and specified in the Java SE API Specification.
Some preview APIs are described as _reflective_ by the Java SE Platform Specification, principally the java.lang.{reflect,invoke} and javax.{lang.model,annotation,tools} packages. The rule for use of reflective preview APIs is as follows:
- Whether preview features are enabled or disabled, a Java compiler must produce a _preview warning_ if a reflective preview API element is used (overridden, invoked, or referenced by name) in the declaration of a program element (whether explicitly or implicitly declared), unless:
The declaration where the use of a reflective preview API element appears is within the same module as the declaration of the reflective preview API element; or
The use is within a declaration that is annotated to suppress preview warnings (§9.6.4.5); or
The use is within an import declaration that imports the preview API element.
For all other preview APIs in the Java SE Platform Specification, the rules for use are as follows:
- If preview features are disabled, then a compile-time error occurs if either (i) a preview API element, or (ii) a type declared using a preview language feature, is used (overridden, invoked, or referenced by name) in the declaration of a program element (whether explicitly or implicitly declared), unless:
The declaration where the use of a preview API element appears is within the same module as the declaration of the preview API element.
- If preview features are enabled, then a Java compiler must produce a _preview warning_ if either (i) a preview API element, or (ii) a type declared using a preview language feature, is used (overridden, invoked, or referenced by name) in the declaration of a program element (whether explicitly or implicitly declared), unless:
The declaration where the use of a preview API element appears is within the same module as the declaration of the preview API element; or
The use is within a declaration that is annotated to suppress preview warnings (§9.6.4.5); or
The use is within an import declaration that imports the preview API element.
-----
Attachments
Issue Links
- relates to
-
JDK-8231433 1.5: Robust handling of code using essential APIs associated with preview features
-
- Resolved
-
-
JDK-8250769 javac support for Preview APIs
-
- Closed
-
-
JDK-8195734 JEP 12: Preview Features
-
- Completed
-