Preview APIs in the Java Platform

[Alex Buckley]

On 3/3/2020 1:15 PM, Alex Buckley wrote:
> Ultimately, though, the best way to provoke feedback on a feature is to 
> ship it in the GA binary of a JDK feature release. This approach has 
> worked well for preview language features, where the Java community has 
> accepted the idea of non-final features that are disabled by default and 
> can thus be changed in response to feedback. Ideally, we want a way to 
> ship highly-evolved but non-final APIs in a JDK feature release, without 
> distorting the API by relocating its packages and modules, and without 
> misleading developers about its status.

I am pleased to report that http://openjdk.java.net/jeps/12 has been 
updated to define preview APIs as the third kind of preview feature, 
alongside preview language features and preview VM features.

The connection between preview language features and preview APIs is 
strong. We now have preview language features that allow ordinary code 
to declare new types (e.g., record classes, sealed classes), which means 
that not only do we have to flag where a declaration relies on a 
non-final feature (`record Point(..) {..}`), but we also have to flag 
where code uses the declaration (`new Point(..)`), since it relies 
indirectly on a non-final feature too. JEP 12 always suggested this 
double-sided flagging, but it emerges more clearly once preview APIs are 
in the story -- using your own record class `Point` is akin to using a 
preview API in java.*. The use of preview language features, types 
declared using preview language features, and preview APIs is discussed 
in a unified way in the section "Use of Preview Features".

Other topics of interest are the four-way categorization of preview APIs 
(with special rules to support use of "reflective" preview APIs -- also 
not new, but clearer now), and the impact of preview APIs in java.lang.

javac's support for preview APIs is on track for JDK 16. The CSR 
(https://bugs.openjdk.java.net/browse/JDK-8250769) includes a concise 
overview of what happens when you use each kind of preview feature.

Alex