Preview APIs in the Java Platform

[Alex Buckley]

Hi Jay,

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: 
https://mail.openjdk.java.net/pipermail/jdk-dev/2019-September/003325.html

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 
Features" section:

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

Also:

- "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 
https://bugs.openjdk.java.net/browse/JDK-8249554.

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

Alex

On 8/12/2020 4:24 AM, Jayaprakash Arthanareeswaran wrote:
> Hi Alex,
> 
> As per the mail [1] 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?
> 
> Regards,
> Jay
> 
> [1] http://mail.openjdk.java.net/pipermail/jdk-dev/2019-August/003234.html