Preview APIs in the Java Platform

[Alex Buckley]

A few follow-up points:

On 3/3/2020 1:15 PM, Alex Buckley wrote:
> 3. Preview APIs are unavailable by default. To use them, a developer 
> "opts in" in the same way as for preview language features: `--release N 
> --enable-preview` at compile time. The class files of the developer's 
> program are marked to depend on the preview APIs of Java version N, as 
> if the program had used preview language features. Accordingly, the 
> class files must be executed with `--enable-preview` at run time, and 
> only the same JDK version.
> 
> Java 14 already has "APIs associated with preview language features" 
> that work this way, such as `java.lang.Record`. In future, such APIs 
> would simply be cast as preview APIs. The existing private mechanism 
> that identifies them to `javac` and `javadoc` -- 
> `@jdk.internal.PreviewFeature` -- will be used for all preview APIs.

To clarify: The JLS will list only those preview APIs which are 
essential to preview language features, and will not list preview APIs 
which are orthogonal to the Java language.

The Java SE Platform Specification will need to list the latter group of 
preview APIs -- straightforward, since the Platform Spec already lists 
preview JEPs -- and say "These APIs exist only when preview features are 
enabled."  We already do something like this in the Platform Spec for 
14, to make record serialization/deserialization exist only when preview 
features are enabled at run time -- see 
http://cr.openjdk.java.net/~iris/se/14/latestSpec/java-se-14-annex-4.html

Switching gears slightly:  If some future version of Java SE has a 
preview feature called Virtual Threads, then the feature would include 
significant extensions to JVM TI and JNI. These are C-language APIs, so 
we can't mark the new API points as "preview" and have them be disabled 
by default at compile time. Still, feedback is important, so we would 
plan to include new C-language API points in the most direct way 
possible (e.g., no names mangled with `__preview` prefixes) and then 
heavily document their non-final status.

> Beyond APIs, incubation has been used for tools, e.g., 
> `jdk.incubator.jpackage` in JDK 14. However, it has little real meaning 
> there. A tool that's good enough to ship in a JDK feature release has 
> already achieved a high level of quality and is ready for a final round 
> of polishing for its command line options. As long as the tool displays 
> a suitable message about its non-final status, it can legitimately be 
> called a "preview tool" and placed in a module in the ordinary `jdk` 
> namespace rather than the `jdk.incubator` namespace.

I want to emphasize that previewing is meaningful not only in the Java 
language, JVM, and SE API, but also in "supported" JDK APIs and tools:

1. Supported JDK APIs are APIs outside `java.*` that we export, 
recommend, and steward as carefully as if they were inside. Examples: 
JDI (`com.sun.jdi` in `jdk.jdi`) and the Compiler Tree API 
(`com.sun.source.tree` in `jdk.compiler`). If some future version of 
Java SE has a preview feature called Virtual Threads, then the feature 
would include significant extensions to JDI as well as JVM TI and JNI; 
we would plan to identify the Java-language API points in JDI as preview 
APIs.

2. Supported JDK tools means the majority of JDK tools. They're not 
mentioned in the Platform Spec, but they have a long life and we 
maintain them in the usual careful, compatible way. (We even regard them 
as having "specifications" -- see 
https://docs.oracle.com/en/java/javase/14/docs/specs/man/index.html) 
For example, consider `jpackage`: it gathered initial feedback with a 
dedicated EA build on jdk.java.net, so a plausible next step would have 
been to preview in `jdk.jpackage` rather than to incubate in 
`jdk.incubator.jpackage`. When a tool is previewed, I don't believe the 
--enable-preview flag is worthwhile; what's important is a loud start-up 
message that the tool is in preview, and may change if/when it becomes 
permanent.

Alex