JDK-8200440 : Add JVM support for preview features
  • Type: CSR
  • Component: hotspot
  • Sub-Component: runtime
  • Priority: P3
  • Status: Closed
  • Resolution: Approved
  • Fix Versions: 11
  • Submitted: 2018-03-29
  • Updated: 2018-09-20
  • Resolved: 2018-04-05
Related Reports
CSR :  
Relates :  
Relates :  
Description
Summary
-------

Add JVM 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 addressed. While we could provide binary snapshots 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, JVM 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 JVM, support for preview features is enabled via a new command-line option, namely --enable-preview.  This option effectively unlocks class files in which preview features for a given Java SE release are enabled.  These class files must have a class file major_version set to the current platform version and a minor_version with all 16 bits set.  The JVM will not load class files with this special major_version, minor_version setting unless --enable-preview is specified.

Specification
-------------

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

If the --enable-preview flag is not present, the JVM should continue to behave normally - e.g. as if preview features did not exist. As a result, an attempt to load a class file containing the special major_version, minor version will fail with a java.lang.UnsupportedClassVersionError exception. To help the user, the JVM 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 present then the JVM will allow loading of class files whose major_version is set to the current platform major_version and whose minor_version has all 16 bits set.  The JVM will only load preview classes for the current release.  Attempts to load classes with a major_version that is less than the current major version and with a minor_version with all 16 bits set will result in a java.lang.UnsupportedClassVersionError exception, even if --enable-preview is specified.  Note that attempts to load classes with a major version that is greater than the current version will continue to result in a java.lang.UnsupportedClassVersionError exception regardless of the minor_version value or specifying of --enable-preview.

Additionally, the JVM will provide logging support so users can know when preview features are being loaded during program execution.

In order to support the special preview major_version, minor_version, the JVM rules for what class file major and minor versions it will accept are being changed.  Please see [2] for rationale and details for this change.

The JVM will throw java.lang.UnsupportedClassVersionError exceptions for any class file version that is not one of the following:

 - Major_version = 45, any minor_version
 - Major_version >= 46 and major_version <= current_major_version and minor_version = 0
 - Major_version = current_major_version and minor_version = 65535 and --enable-preview is present.

[1] http://openjdk.java.net/jeps/12

[2] https://bugs.openjdk.java.net/browse/JDK-8200338

Comments
No changes are needed to the invocation API for --enable-preview.
05-04-2018

An additional comment: does some aspect of the invocation API need to change to allow the --enable-preview option to be tunneled through in a standard manner?
05-04-2018

Moving to Approved.
05-04-2018

Filed JDK-8201127: Add major/minor version methods to UnsupportedClassVersionError
05-04-2018

It might be a kindness to those seeing UnsupportedClassVersionError if the error type were augmented to include methods to retrieve the major and minor versions.
04-04-2018

The UnsupportedClassVersionError message will contain version information. Here is a sample message: java.lang.UnsupportedClassVersionError: [class-name] (class file version 54.65535) was compiled with preview features that are unsupported. This version of the Java Runtime only recognizes preview features for class file version 55.65535
04-04-2018