Summary

More clearly specify the value of the java.{vm.}?specification.version system properties.

Problem

It hasn't been clear in the past how the java.{vm.}?specification.version property values relate to the "java.version" system property, or how the values might change in a Maintenance Release.

As of JEP 322 "Time-Based Release Versioning", we have a well-defined progression of FEATURE version numbers, and the "java.specification.version" and "java.vm.specification.version" system properties get their value from the VERSION_FEATURE make variable.

We can clarify what values to expect from the java.{vm.}?specification.version properties.

Solution

In System.getProperties(), indicate that the value of the "java.specification.version" and "java.vm.specification.version" system properties come from the $FEATURE element of Runtime.Version.

Specification

    java.lang.System.getProperties()
    --------------------------------
*** 605,616 ****
       * <tr><th scope="row">{@code java.vm.specification.version}</th>
!      *     <td>Java Virtual Machine specification version which may be
!      *     interpreted as a {@link Runtime.Version}</td></tr>
       * <tr><th scope="row">{@code java.vm.specification.vendor}</th>
--- 605,617 ----
       * <tr><th scope="row">{@code java.vm.specification.version}</th>
!      *     <td>Java Virtual Machine specification version, whose value is the
!      *     {@linkplain Runtime.Version#feature feature} element of the
!      *     {@linkplain Runtime#version() runtime version}</td></tr>
       * <tr><th scope="row">{@code java.vm.specification.vendor}</th>
*** 619,630 ****
       * <tr><th scope="row">{@code java.specification.version}</th>
!      *     <td>Java Runtime Environment specification version which may be
!      *     interpreted as a {@link Runtime.Version}</td></tr>
       * <tr><th scope="row">{@code java.specification.vendor}</th>
--- 620,632 ----
       * <tr><th scope="row">{@code java.specification.version}</th>
!      *     <td>Java Runtime Environment specification version, whose value is
!      *     the {@linkplain Runtime.Version#feature feature} element of the
!      *     {@linkplain Runtime#version() runtime version}</td></tr>
       * <tr><th scope="row">{@code java.specification.vendor}</th>