JDK-8275888 : Add valueOf(Runtime.Version) factory to SourceVersion
  • Type: CSR
  • Component: core-libs
  • Sub-Component: javax.lang.model
  • Priority: P4
  • Status: Closed
  • Resolution: Approved
  • Fix Versions: 18
  • Submitted: 2021-10-25
  • Updated: 2022-04-18
  • Resolved: 2021-10-28
Related Reports
CSR :  
Relates :  
Relates :  
Description
Summary
-------

Provide mapping between `SourceVersion` values and `Runtime.Version` values. 

Problem
-------

Helpful to be able to map between `SourceVersion` values and `Runtime.Version` in various contexts. Indirectly, this provides a mapping between version *strings* and `SourceVersion` values via the  `Runtime.Version.parse()` method.

Solution
--------

Add two methods to `SourceVersion`, one mapping `SourceVersion` to `Runtime.Version`, the other mapping `Runtime.Version` to `SourceVersion`.

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

    +
    +    /**
    +     * {@return the latest source version that is usable under the
    +     * runtime version argument} If the runtime version's {@linkplain
    +     * Runtime.Version#feature() feature} is greater than the feature
    +     * of the {@linkplain #runtimeVersion() runtime version} of the
    +     * {@linkplain #latest() latest source version}, an {@code
    +     * IllegalArgumentException} is thrown.
    +     *
    +     * <p>Because the source versions of the Java programming language
    +     * have so far followed a linear progression, only the feature
    +     * component of a runtime version is queried to determine the
    +     * mapping to a source version. If that linearity changes in the
    +     * future, other components of the runtime version may influence
    +     * the result.
    +     *
    +     * @apiNote
    +     * An expression to convert from a string value, for example
    +     * {@code "17"}, to the corresponding source version, {@code
    +     * RELEASE_17}, is:
    +     *
    +     * <pre>{@code SourceVersion.valueOf(Runtime.Version.parse("17"))}</pre>
    +     *
    +     * @param rv runtime version to map to a source version
    +     * @throws IllegalArgumentException if the feature of version
    +     * argument is greater than the feature of the platform version.
    +     */
    +    public static SourceVersion valueOf(Runtime.Version rv) {
    +        // Could also implement this as a switch where a case was
    +        // added with each new release.
    +        return valueOf("RELEASE_" + rv.feature());
    +    }
    +
    +    /**
    +     * {@return the least runtime version that supports this source
    +     * version; otherwise {@code null}} The returned runtime version
    +     * has a {@linkplain Runtime.Version#feature() feature} large
    +     * enough to support this source version and has no other elements
    +     * set.
    +     *
    +     * Source versions greater than or equal to {@link RELEASE_6}
    +     * have non-{@code null} results.
    +     */
    +    public Runtime.Version runtimeVersion() {
    +        // The javax.lang.model API was added in JDK 6; for now,
    +        // limiting supported range to 6 and up.
    +        if (this.compareTo(RELEASE_6) >= 0) {
    +            return Runtime.Version.parse(Integer.toString(ordinal()));
    +        } else {
    +            return null;
    +        }
    +    }



Comments
Moving to Approved.
28-10-2021