JDK-8275308: Add valueOf(Runtime.Version) factory to SourceVersion #5973

jddarcy · 2021-10-15T23:17:50Z

I wanted to get input on the design of API of the method before writing the tests.

The new factory method maps from a Runtime.Version object, a object which formally modes the version of the JDK, to a corresponding SourceVersion object.

Given the current histories of versioning of the JDK and SourceVersion this amount to mapping "JDK N" to RELEASE_N, for example, JDK 17 to RELEASE_17, etc. As mentioned in the API note, this could potentially change in the future if the release model changes. Runtime.Version has added in JDK 9, but earlier versions can be modeled. Note that no attempt is made to map "1.2" to RELEASE_2 and that since Runtime.Version grammar does not allow a leading 0 term, RELEASE_0 will not be returned by the new method.

Another design point: an out-of-range feature version is treated as an error so a Runtime.Version with a feature of 19 mapped in JDK 18 will fail with an IllegalArgumentException rather than saturating at RELEASE_18. If saturating would be more helpful for the envisioned use cases, I'm open to changing the spec accordingly.

CSR to follow once the API is nailed down.

Progress

Change must not contain extraneous whitespace
Commit message must refer to an issue
Change must be properly reviewed

Issue

JDK-8275308: Add valueOf(Runtime.Version) factory to SourceVersion

Reviewers

Jonathan Gibbons (@jonathan-gibbons - Reviewer) ⚠️ Review applies to 4517e54

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.java.net/jdk pull/5973/head:pull/5973
$ git checkout pull/5973

Update a local copy of the PR:
$ git checkout pull/5973
$ git pull https://git.openjdk.java.net/jdk pull/5973/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 5973

View PR using the GUI difftool:
$ git pr show -t 5973

Using diff file

Download this PR as a diff file:
https://git.openjdk.java.net/jdk/pull/5973.diff

bridgekeeper · 2021-10-15T23:18:31Z

👋 Welcome back darcy! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

openjdk · 2021-10-15T23:20:24Z

@jddarcy The following label will be automatically applied to this pull request:

compiler

When this pull request is ready to be reviewed, an "RFR" email will be sent to the corresponding mailing list. If you would like to change these labels, use the /label pull request command.

mlbridge · 2021-10-15T23:23:57Z

Webrevs

pavelrappo · 2021-10-15T23:24:53Z

src/java.compiler/share/classes/javax/lang/model/SourceVersion.java

+     * {@code 17}, to the corresponding source version, {@code
+     * RELEASE_17}, is<br>:
+     *
+     * {@code SourceVersion.valueOf(Runtime.Version.parse(Integer.toString(17)))


Suggested change

* {@code SourceVersion.valueOf(Runtime.Version.parse(Integer.toString(17)))

* {@code SourceVersion.valueOf(Runtime.Version.parse(Integer.toString(17)))}

I understand that this PR is an invitation to a discussion, not the final solution. Still, it's easier to reason about API whose doc comments render properly.

Doh! Sorry, fixed.

jonathan-gibbons · 2021-10-16T00:10:58Z

src/java.compiler/share/classes/javax/lang/model/SourceVersion.java

+     * @apiNote
+     * An expression to convert from an integer value, for example
+     * {@code 17}, to the corresponding source version, {@code
+     * RELEASE_17}, is<br>:
+     *
+     * {@code SourceVersion.valueOf(Runtime.Version.parse(Integer.toString(17)))}


IMO, The use of integer value in the example is something of a distraction, and suggests a hole in the Runtime.Version API. IMO, a more likely use case is for code to have a string representing a version, perhaps found as an argument on the command line

mbien · 2021-10-16T03:02:07Z

although the new factory method is quite useful to convert from one version representation to another. Unfortunately, I don't think it would solve one particular use case (although a very niche one). NetBeans for example relies on javac for all its editor features and can optionally use a newer javac than the JDK has, on which it is running on. This allows to have java 17 editor features while starting NB on JDK 8 (for whatever reason).

That is why you can find code like in apache/netbeans@56cf1c5 all over the place since it has to check a feature version against an enum which might not be there. And that is why my first thought went to "wouldn't it be nice if we could just compare ordinals or ask SourceVersion for the feature version int". Calling version.feature() >= 11 would not require having access to the RELEASE_11 enum you would need to compare the version with.

Calling version.compareTo(SourceVersion.valueOf(Runtime.Version.parse("11")))) >= 0 wouldn't help a lot since it basically has to throw exceptions since it can't just make up enums.

But this is so niche that it is probably not worth considering.

NB could just put

   public static boolean supports(SourceVersion model, int featureVersionToCheck) {
       return model.ordinal() >= featureVersionToCheck;
   }

somewhere which will work until the unlikely event of the enum having non-feature versions before it needs to be changed. (or just keep doing the static initializer workaround)

jonathan-gibbons · 2021-10-16T03:23:07Z

Would it help to have a method that provides the inverse mapping

Runtime.Version SourceVersion.toRuntimeVersion()

mbien · 2021-10-16T16:11:29Z

@jonathan-gibbons I think that would help indeed. The conversion method would always be able to return a runtime version without throwing exceptions, which would make it a convenient way to access the feature version int. It seems to be also forward compatible to all (prob. unlikely) scenarios of SourceVersion adding non-feature-version enums.

hns · 2021-10-18T08:53:18Z

FWIW there is one place in javadoc that would also benefit from a SourceVersion to Runtime.Version conversion method. (That code would be less ugly if it used ordinal(), the idea was that it would fail more predictably this way if the version naming pattern was ever abandoned.)

jdk/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Extern.java

Lines 336 to 342 in ebb1363

    
           private int getSourceVersionNumber() { 
        
               SourceVersion sourceVersion = configuration.docEnv.getSourceVersion(); 
        
               // TODO it would be nice if this was provided by SourceVersion 
        
               String versionNumber = sourceVersion.name().substring(8); 
        
               assert SourceVersion.valueOf("RELEASE_" + versionNumber) == sourceVersion; 
        
               return Integer.parseInt(versionNumber); 
        
           }

jddarcy · 2021-10-20T06:12:12Z

In the latest push, stubbed in support for the reverse mapping from SourceVersion to a runtime version. For now, limiting the mapping to RELEASE_9 and higher since Runtime.Version was added in 9.

jonathan-gibbons · 2021-10-21T23:58:45Z

src/java.compiler/share/classes/javax/lang/model/SourceVersion.java

+        if (feature > Runtime.version().feature()) {
+            throw new IllegalArgumentException("No matching SourceVersion for " + rv);
+        } else {


Using Runtime.version() as a stand-in for the max SourceVersion seems non-obvious. Would it be better to use SourceVersion.latest().runtimeVersion() instead?

What about when running this API on JDK N-1?

if could be potentially dropped since valueOf("RELEASE_" + feature) is throwing IAE already.

Updated as suggested.

Using Runtime.version() as a stand-in for the max SourceVersion seems non-obvious. Would it be better to use SourceVersion.latest().runtimeVersion() instead?

What about when running this API on JDK N-1?

Updated the supported range to go up to the feature corresponding to SourceVersion.latest().

I think this affects the doc comment and CSR.

Right; I think the the current spec

* ... 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.

does reflect that.

hns · 2021-10-22T07:53:44Z

In the latest push, stubbed in support for the reverse mapping from SourceVersion to a runtime version. For now, limiting the mapping to RELEASE_9 and higher since Runtime.Version was added in 9.

Thanks for adding the reverse mapping! Is there a problem with Source.Version representing a version earlier than 9, other than that it was added in that release? Supporting earlier versions would be very useful for javadoc, where we support versions starting from 7.

jddarcy · 2021-10-25T15:46:56Z

In the latest push, stubbed in support for the reverse mapping from SourceVersion to a runtime version. For now, limiting the mapping to RELEASE_9 and higher since Runtime.Version was added in 9.

Thanks for adding the reverse mapping! Is there a problem with Source.Version representing a version earlier than 9, other than that it was added in that release? Supporting earlier versions would be very useful for javadoc, where we support versions starting from 7.

Added support back to 6, the release the javax.lang.model API was added. Strictly speaking release 6, 7, and 8 aren't modeled by Runtime.Version, but just using the feature value can be reasonable.

I don't think it is worthwhile to formally map, for instance, RELEASE_5 to something like RuntimeVersion.parse("5.0") or RuntimeVersion.parse("5.0.0") to try to model the versioning scheme used then.

jddarcy · 2021-10-25T21:57:31Z

In the latest push, stubbed in support for the reverse mapping from SourceVersion to a runtime version. For now, limiting the mapping to RELEASE_9 and higher since Runtime.Version was added in 9.

Thanks for adding the reverse mapping! Is there a problem with Source.Version representing a version earlier than 9, other than that it was added in that release? Supporting earlier versions would be very useful for javadoc, where we support versions starting from 7.

Changed to RELEASE 6 and later in the latest push; the javax.lang.model API was added in JDK 6.

mbien · 2021-10-25T22:11:02Z

would the doc need @since 18 tags?

jddarcy · 2021-10-25T22:13:52Z

/csr needed

jddarcy · 2021-10-25T22:14:50Z

CSR now available for review: https://bugs.openjdk.java.net/browse/JDK-8275888

openjdk · 2021-10-25T22:15:01Z

@jddarcy this pull request will not be integrated until the CSR request JDK-8275888 for issue JDK-8275308 has been approved.

jddarcy · 2021-10-25T22:24:39Z

would the doc need @since 18 tags?

Sure; added.

jddarcy · 2021-10-27T14:07:05Z

Any more comments on this PR?

jonathan-gibbons · 2021-10-28T20:59:38Z

src/java.compiler/share/classes/javax/lang/model/SourceVersion.java

+     * {@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.


openjdk · 2021-10-28T21:46:09Z

@jddarcy This change now passes all automated pre-integration checks.

ℹ️ This project also has non-automated pre-integration requirements. Please see the file CONTRIBUTING.md for details.

After integration, the commit message for the final commit will be:

8275308: Add valueOf(Runtime.Version) factory to SourceVersion

Reviewed-by: jjg

You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed.

At the time when this comment was updated there had been no new commits pushed to the master branch. If another commit should be pushed before you perform the /integrate command, your PR will be automatically rebased. If you prefer to avoid any potential automatic rebasing, please check the documentation for the /integrate command for further details.

➡️ To integrate this PR with the above commit message to the master branch, type /integrate in a new comment.

jddarcy · 2021-10-28T22:10:27Z

/integrate

openjdk · 2021-10-28T22:11:10Z

Going to push as commit 48f3fca.

openjdk · 2021-10-28T22:11:27Z

@jddarcy Pushed as commit 48f3fca.

💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored.

JDK-8275308: Add valueOf(Runtime.Version) factory to SourceVersio

19e8c52

openjdk bot added the rfr Pull request is ready for review label Oct 15, 2021

openjdk bot added the compiler compiler-dev@openjdk.org label Oct 15, 2021

pavelrappo reviewed Oct 15, 2021

View reviewed changes

Fix typo.

bf3e4df

jonathan-gibbons reviewed Oct 16, 2021

View reviewed changes

mbien mentioned this pull request Oct 16, 2021

[jackpot] updated Collection.toArray() refactoring apache/netbeans#3166

Merged

jddarcy added 2 commits October 19, 2021 09:01

Merge branch 'master' into JDK-8275308

75cfc1b

Add support for reverse conversion.

2062fd4

jonathan-gibbons reviewed Oct 21, 2021

View reviewed changes

jddarcy added 3 commits October 25, 2021 07:23

Merge branch 'master' into JDK-8275308

7a7cce0

Initial test support.

9e94e0d

Appease jcheck.

091e268

openjdk bot added rfr Pull request is ready for review and removed rfr Pull request is ready for review labels Oct 25, 2021

Respond to review feedback.

63c1847

openjdk bot added the csr Pull request needs approved CSR before integration label Oct 25, 2021

Add @SInCE tags.

4517e54

jonathan-gibbons approved these changes Oct 28, 2021

View reviewed changes

openjdk bot removed the csr Pull request needs approved CSR before integration label Oct 28, 2021

openjdk bot added the ready Pull request is ready to be integrated label Oct 28, 2021

jddarcy added 3 commits October 28, 2021 14:48

Merge branch 'master' into JDK-8275308

9cede76

Merge branch 'master' into JDK-8275308

053c7e4

Adjust copyrights and add bug id to test.

f33fa42

openjdk bot closed this Oct 28, 2021

openjdk bot added integrated Pull request has been integrated and removed ready Pull request is ready to be integrated rfr Pull request is ready for review labels Oct 28, 2021

mbien mentioned this pull request Dec 1, 2021

Introduce SourceVersion utility. apache/netbeans#3274

Closed

jddarcy deleted the JDK-8275308 branch December 9, 2021 18:48

	* {@code SourceVersion.valueOf(Runtime.Version.parse(Integer.toString(17)))
	* {@code SourceVersion.valueOf(Runtime.Version.parse(Integer.toString(17)))}

JDK-8275308: Add valueOf(Runtime.Version) factory to SourceVersion #5973

JDK-8275308: Add valueOf(Runtime.Version) factory to SourceVersion #5973

Uh oh!

Conversation

jddarcy commented Oct 15, 2021 • edited by openjdk bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Progress

Issue

Reviewers

Reviewing

Uh oh!

bridgekeeper bot commented Oct 15, 2021

Uh oh!

openjdk bot commented Oct 15, 2021

Uh oh!

mlbridge bot commented Oct 15, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Webrevs

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pavelrappo Oct 15, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mbien commented Oct 16, 2021

Uh oh!

jonathan-gibbons commented Oct 16, 2021

Uh oh!

mbien commented Oct 16, 2021

Uh oh!

hns commented Oct 18, 2021

Uh oh!

jddarcy commented Oct 20, 2021

Uh oh!

jonathan-gibbons Oct 21, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jddarcy Oct 27, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hns commented Oct 22, 2021

Uh oh!

jddarcy commented Oct 25, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jddarcy commented Oct 25, 2021

Uh oh!

mbien commented Oct 25, 2021

Uh oh!

jddarcy commented Oct 25, 2021

Uh oh!

jddarcy commented Oct 25, 2021

Uh oh!

openjdk bot commented Oct 25, 2021

Uh oh!

jddarcy commented Oct 25, 2021

Uh oh!

jddarcy commented Oct 27, 2021

Uh oh!

Choose a reason for hiding this comment

Uh oh!

openjdk bot commented Oct 28, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jddarcy commented Oct 28, 2021

jddarcy commented Oct 15, 2021 •

edited by openjdk bot

Loading

mlbridge bot commented Oct 15, 2021 •

edited

Loading

pavelrappo Oct 15, 2021 •

edited

Loading

jonathan-gibbons Oct 21, 2021 •

edited

Loading

jddarcy Oct 27, 2021 •

edited

Loading

jddarcy commented Oct 25, 2021 •

edited

Loading

openjdk bot commented Oct 28, 2021 •

edited

Loading