8387875: [lworld] Provide value-class-preview.md file

[liach]

This is some extremely basic overview about value class migrations.

1. Build: I intentionally skipped the streamlined build system installed by David Beaumont. Instead, I stressed the custom handling used by Value Objects JEP. (The "Preview Classes in Interim javac" section might go to general documentation later.)

2. Testing: I started from the motivations/goals and describe how those goals are accomplished.

3. Wrapper class caches: Some simple overview.

There are definitely more topics to cover; feel free to raise.

Paging @jddarcy and @viktorklang-ora for proofreading.

---

• I confirm that I make this contribution in accordance with the OpenJDK Interim AI Policy.

---

Progress

• Change must not contain extraneous whitespace
• Commit message must refer to an issue
• Change must be properly reviewed (1 review required, with at least 1 Committer)

Issue

• JDK-8387875: [lworld] Provide value-class-preview.md file (Enhancement - P2)

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.org/valhalla.git pull/2633/head:pull/2633
$ git checkout pull/2633

Update a local copy of the PR:
$ git checkout pull/2633
$ git pull https://git.openjdk.org/valhalla.git pull/2633/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 2633

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

Using diff file

Download this PR as a diff file:
https://git.openjdk.org/valhalla/pull/2633.diff

Using Webrev

Link to Webrev Comment

[bridgekeeper]

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

[openjdk]

❗ This change is not yet ready to be integrated.
See the Progress checklist in the description for automated requirements.

[jddarcy]

So, with the current system, consequently, any needed testing of "is preview enabled" must be done at runtime rather than via a compile-time macro?
(The other little code gen systems used in the JDK have a more expressive set of primitives. In my estimation, the simple system here is good for the purpose it is being used for, but it is helpful to document it here.)

[liach]

Yes. I don't understand how a compile-time macro can work - we have one runtime that must support both preview-on and preview-off runs.

[jddarcy]

In the space of generate-different-source-code-from-a-template solutions, it would be possible to have code conditionally emitted for one case but not the other. The solution used for JEP 401 currently just uncomments the value modifier.

[liach]

We tried to use annotation processors and discovered that it just introduced unnecessary hassles and complexities beyond what is required for JEP 401. I have described the JEP 401 process here; we can tweak this document if we do tweak this pipeline in the future.

[jddarcy]

I understand some of the history for the transitory use of annotation processors, but the readers of this document might have not that history (and might not care about it either ;-) ).

Given that the general shape of the solution is "we have generating preview-specific versions of source files which get compiled into preview-specific class files," the current mechanism we are choosing to do the generation has very limited functionality, which is sufficient for the purposes at hand. However, that mechanism is less capable than several analagous mechanisms elsewhere in the JDK build.

[jddarcy]

And once the text of the note if finalized, links to it in // comments should be added to the wrapper classes and the java.time classes.

[viktorklang-ora]

Thanks for taking this on, @liach!

[liach]

Updated. Please help proofread the latest version, thanks!

[viktorklang-ora]

After commentsI had some minor comments, and after addressing those I think this is ready from my point-of-view. I'll let @jddarcy decide if anything more is necessary.

[mlbridge]

Webrevs

• 05: Full - Incremental (9fa9a94f)
• 04: Full - Incremental (4d0cec8b)
• 03: Full - Incremental (6d7698a2)
• 02: Full - Incremental (5530feb7)
• 01: Full - Incremental (6c8522a5)
• 00: Full (a007bbd1)

[viktorklang-ora]

This is LGTM after considering my latest comments.

[jddarcy]

To clarify,
"To accomplish this, a built JDK uses..."

That is, this section is discussing the artifact people run, not the source structure, etc.

[jddarcy]

Other than the small edit to the text, I think the only remaining task is to add cross references in non-javadoc comments in the affected files, the wrapper classes, etc. to this information.

[liach]

@dansmithcode Do you think a one liner in each of the migrated class like:

// See doc/value-class-preview.md for how value classes are declared in the Java Platform APIs.

would be the best way forward? Feel free to suggest exact wording too.