Summary

Revise the version-string scheme of the Java SE Platform and the JDK, and related versioning information, for present and future time-based release models per JEP 322.

Problem

The version-string scheme introduced by JEP 223 is not well-suited to the new release model, under which we intend to ship new releases of the Java SE Platform and the JDK on a strict, six-month cadence.

Further motivation and background is given in JEP 322.

Solution

• Redefine the version-number component of version strings, as specified by JEP 223, to interpret the first four elements as $FEATURE.$INTERIM.$UPDATE.$PATCH.

• Revise the Runtime.Version API as follows:

  • Add four new int-returning accessor methods for the principal components of version numbers as defined above: feature(), interim(), update(), and patch().

  • Redefine the existing accessor methods major(), minor(), and security() to return the same values as feature(), interim(), and update(), respectively.

  • Deprecate the existing accessor methods, but not for removal, with advice to use the corresponding new methods. This will help make the new semantics of version numbers clear to developers.

• Define two new system properties:

  • java.version.date — The general-availability (GA) date of the release, in ISO-8601 YYYY-MM-DD format. For early-access releases this will be the intended GA date, i.e., some date in the future.

  • java.vendor.version — An implementor-specific product version string, optionally assigned by the individual or organization that produces a specific implementation. If not assigned at build time then it has no value; otherwise, its value is a non-empty string that matches the regular expression \p{Graph}+.

• Revise the output of the java launcher's version-report options to display these properties, when appropriate, and also to indicate whether a release is a long-term-support ("LTS") release.

Additional background on the overall solution is given in JEP 322.

Specification

Changes to the Runtime.Version and System classes are documented in the attached file 8192855-specdiff.zip, which is also viewable here.

The output of the java launcher's version-report options is changed as follows, where ${LTS} expands to "\u0020LTS" if the first three characters of $OPT are "LTS", and ${JVV} expands to "\u0020${java.vendor.version}" if that system property is defined:

$ java --version
openjdk ${java.version} ${java.version.date}${LTS}
${java.runtime.name}${JVV} (build ${java.runtime.version})
${java.vm.name}${JVV} (build ${java.vm.version}, ${java.vm.info})
$ 

$ java --show-version < ... >
openjdk ${java.version} ${java.version.date}${LTS}
${java.runtime.name}${JVV} (build ${java.runtime.version})
${java.vm.name}${JVV} (build ${java.vm.version}, ${java.vm.info})
[ ... ]
$ 

$ java --full-version
openjdk ${java.runtime.version}
$ 

$ java -version
openjdk version \"${java.version}\" ${java.version.date}${LTS}
${java.runtime.name}${JVV} (build ${java.runtime.version})
${java.vm.name}${JVV} (build ${java.vm.version}, ${java.vm.info})
$ 

$ java -showversion < ... >
openjdk version \"${java.version}\" ${java.version.date}${LTS}
${java.runtime.name}${JVV} (build ${java.runtime.version})
${java.vm.name}${JVV} (build ${java.vm.version}, ${java.vm.info})
[ ... ]
$ 

$ java -fullversion
openjdk full version \"${java.runtime.version}\"
$ 

The release file in the root directory of a JDK build image will contain two new properties:

• JAVA_VERSION_DATE — The value of the java.version.date system property.

• IMPLEMENTOR_VERSION — The value of the java.vendor.version system property, if defined; otherwise, this property is not defined. (This is named IMPLEMENTOR_VERSION for consistency with the existing IMPLEMENTOR property.)

Compatibility

The changes described here introduce two minor behavioral incompatibilities:

• The output of the java launcher's version-report options now includes the version date at the end of the first line, possibly followed by "\u0020LTS". Existing code that parses this output under the assumption that the last token on the line is the version number may require adjustment.

• The output of the java launcher's --version, --show-version, -version, and -showversion options will include the value of the java.vendor.version system property on the second and third lines, if that value differs from that of the java.version. Existing code that parses this output may require adjustment.

There is one minimal behavioral incompatibility:

• JEP 223 specifies the security() method of the Runtime.Version API to return the value of the $SECURITY element of the version number. That element is not incremented when the element that precedes it, $MINOR, is incremented. This proposal renames the $SECURITY element to $UPDATE and clears that element whenever the element that precedes it, $INTERIM (formerly $MINOR), is incremented. The redefinition of security() in terms of update() is therefore, in theory, an incompatible change. This API was introduced in JDK 9, however, and no releases of JDK 9 with a non-zero value of $MINOR are envisioned, so in practice this change should have minimal impact.