Details

    • Type: CSR
    • Status: Closed
    • Priority: P2
    • Resolution: Approved
    • Fix Version/s: 10
    • Component/s: core-libs
    • Labels:
      None
    • Compatibility Kind:
      behavioral
    • Compatibility Risk:
      low
    • Compatibility Risk Description:
      Hide
      Existing code, such as shell scripts, that parse the version-report output of the "java" launcher may require minor adjustment since that output will now include additional information.
      Show
      Existing code, such as shell scripts, that parse the version-report output of the "java" launcher may require minor adjustment since that output will now include additional information.
    • Interface Kind:
      Java API, System or security property, add/remove/modify command line option
    • Scope:
      SE

      Description

      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.

        Issue Links

          Activity

          Hide
          darcy Joe Darcy added a comment -

          Adding system property to the set of kinds of interfaces modified by this CSR.

          Show
          darcy Joe Darcy added a comment - Adding system property to the set of kinds of interfaces modified by this CSR.
          Hide
          darcy Joe Darcy added a comment -

          Moving to Provisional; please attach the specdiff before the request is finalized.

          Show
          darcy Joe Darcy added a comment - Moving to Provisional; please attach the specdiff before the request is finalized.
          Hide
          darcy Joe Darcy added a comment -

          If the existing methods from JEP 223 are deprecated and new methods to access the sequential components of a version are added, I would prefer to see method names like "first()", "second()", "third()" or something else less tied to the particular semantics being assigned to those components today under JEP 322. Does $INTERIM come before $UPDATE or $UPDATE before $INTERIM? To me it is clearer that "second()" should come before "third()" regardless of how the release model may evolve in the future.

          In any case, opinions on such matter differ and I'm voting to approve the request in its current form.

          Show
          darcy Joe Darcy added a comment - If the existing methods from JEP 223 are deprecated and new methods to access the sequential components of a version are added, I would prefer to see method names like "first()", "second()", "third()" or something else less tied to the particular semantics being assigned to those components today under JEP 322. Does $INTERIM come before $UPDATE or $UPDATE before $INTERIM? To me it is clearer that "second()" should come before "third()" regardless of how the release model may evolve in the future. In any case, opinions on such matter differ and I'm voting to approve the request in its current form.

            People

            • Assignee:
              mr Mark Reinhold
              Reporter:
              mr Mark Reinhold
              Reviewed By:
              Alan Bateman, Iris Clark, Mandy Chung
            • Votes:
              0 Vote for this issue
              Watchers:
              6 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: