Preview APIs in the Java Platform
alex.buckley at oracle.com
Wed Aug 12 19:16:03 UTC 2020
Subsequent to my August 2019 mail, I sent a mail in September 2019 that
disavowed use of a Java SE annotation for indicating APIs associated
with preview language features:
Since then, we have seen "APIs associated with preview language
features" be subsumed by "preview APIs". How is the status of a preview
API indicated? According to JEP 12's "Specifications of Preview
- "Preview APIs are specified in the javadoc of the API Specification
for Java SE, and must clearly indicate their non-final, impermanent status."
- "The Umbrella JSR also provides a definitive list of the preview API
elements in the release."
- "In Java SE 14, prior to the introduction of preview APIs, the JLS
enumerated the "essential" API elements that were unavoidably associated
with preview language and VM features. The JLS made it a compile-time
error (respectively, a warning) to use such elements if preview features
were disabled (respectively, enabled). This arrangement was the
forerunner of how the JLS treats use of preview APIs, ***with the
exception that preview APIs are enumerated in the Java SE Platform
Specification rather than the JLS.***"
Exactly how the JLS treats use of preview APIs is covered by
How does a compiler know which preview APIs are enumerated in the Java
SE Platform Specification? That's up to the compiler. javac's technique
is to recognize APIs annotated with a JDK-internal annotation.
(@jdk.internal.PreviewFeature in JDK 14 and 15, but moved to a
subpackage of jdk.internal in 16; the details will be clear when Jan
opens the code on compiler-dev.)
On 8/12/2020 4:24 AM, Jayaprakash Arthanareeswaran wrote:
> Hi Alex,
> As per the mail  you sent way back in 2019, you mentioned that the
> preview APIs will be marked
> with @java.lang.annotation.PreviewFeature. However, in JDK 15, the APIs
> appear to be annotated
> with the internal annotation @jdk.internal.PreviewFeature.
> Is this still under discussion and likely to change in future?
>  http://mail.openjdk.java.net/pipermail/jdk-dev/2019-August/003234.html
More information about the jdk-dev