Summary

Add compiler support for JEP 12: Preview Language and VM Features [1].

Problem

Designing language features is a complex process; beside the technical difficulties, there is a more pragmatic one: when designing a new feature, very little is known about how that feature might be used in the real world. Because of that, language designers have to cope with some degree of uncertainty. The language design process could benefit from having a tighter feedback loop - where users could try out the newly added features before they are in a final state, so that relevant feedback could be submitted and acted upon. While we could provide binary snapshot of experimental OpenJDK branches (e.g. Project Amber [2] or Project Valhalla [3]) for people to try out, often the features contained in such branches are - being experimental - fully rotated towards the bleeding edge. We need an easier way for people to try out almost complete but yet not set-in-stone features.

Solution

JEP 12 [1] describes how the compiler, VM and related toolchain might support preview features. A preview feature is, as per JEP description "a new feature of the Java SE Platform that is fully specified, fully implemented, and yet impermanent". In the compiler, support for preview features is enabled in the compiler via a new command-line option, namely --enable-preview. This option effectively unlocks a new source level in which all preview features defined for a given Java SE release are enabled. Since preview features are 'impermanent' it is important for the compiler to warn about usages of such features. Finally, classfile artifacts originating from a compilation unit in which the --enable-preview options was present, should feature a specific minor classfile version mask - this will prevent the JVM from loading such a classfile if the --enable-preview option is not supplied to the runtime environment.

Specification

As part of this change, we plan to add a new javac command-line flag, namely --enable-preview.

If the --enable-preview flag is not present, javac should continue to behave normally - e.g. as if preview features did not exist. As a result, any reference to preview features, either direct (e.g. directly in the source code) or indirect (e.g. through dependency on external classfiles) should result in a compile-time error. To help the user, javac will try (where possible) to signal that a preview feature was found but no corresponding --enable-preview flag was supplied.

If the --enable-preview flag is enabled, the behavior of javac should change as follows:

• javac should additionally recognize preview features (the specific set of additional features recognized by javac will vary from release to release, according to the Java SE platform specifications).

• javac must be able to warn (where possible) of any use of preview features, as a measure to notify users that they are relying on features that might be removed in subsequent releases. Such warnings should be reported under the 'preview' Lint category - which will be added as part of this change. Therefore, developers will have the ability to suppress such warnings in the usual way (e.g. via @SuppressWarnings("preview") or using the command line flag -Xlint:-preview).

• to avoid output clutter, detailed preview warnings will be disabled by default - instead, the compiler will show a mandatory note stating that there were some usages of preview features. The compiler output will prompt the user to recompile with the -Xlint:preview enabled to get the detailed info (this is similar to what happens with unchecked warnings).

• javac must check that the latest source version is selected - e.g. for Java SE 11, --enable-preview can only be used in combination with either -source 11 or --release 11. Note that the selection of the source level must be explicit - either via the -source flag or via the --release flag. Attempts to use --enable-preview with the default, implicit source level will result in a compile-time error.

• any classfile artifacts generated by javac should have a minor version set to the value 0xffff (all bits set).

This change does not alter in any way any of the public API associated with the compiler, such as javax.lang.model [4] or com.sun.source.tree [5]. It is possible that this will change with followup changes to the preview support (where any such followup changes would be covered by additional followup CSR tasks).

1. http://openjdk.java.net/jeps/12
2. http://openjdk.java.net/projects/amber/
3. http://openjdk.java.net/projects/valhalla/
4. https://docs.oracle.com/javase/10/docs/api/java.compiler-summary.html
5. https://docs.oracle.com/javase/10/docs/api/jdk.compiler-summary.html