8383164: [lworld] javadoc updates for value class serialization

[dansmithcode]

Clarifications and cleanups for the java.io API spec related to serialization.

See also JDK-8372300, which updates the serialization specification. (The serialization specification should be regarded as the source of truth, with the API specs providing sometimes-imperfect descriptions of what it says.)

---

• 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-8383164: [lworld] javadoc updates for value class serialization (Bug - P2)

Reviewers

• Chen Liang (@liach - Committer)

Reviewing

Using git

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

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

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 2429

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

Using diff file

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

Using Webrev

Link to Webrev Comment

[bridgekeeper]

👋 Welcome back dlsmith! 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.

[dansmithcode]

No need to say anything special about value classes and Externalizable, so I just rolled this back to its JDK form.

(A value class can choose to implement Externalizable if it wants to, but it won't be able to do anything interesting, because all its fields are immutable. There's no integrity-related reason to have special rules or discussion here.)

[openjdk]

@dansmithcode 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:

8383164: [lworld] javadoc updates for value class serialization

Reviewed-by: liach

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 11 new commits pushed to the lworld branch:

• 6b9eb7d: 8384283: [lworld] Post-parse call devirtualization with unloaded return type fails
• de6aff4: 8384364: [lworld] C2: assert(cloned_flat_array_check->req() == 3) failed: unexpected number of inputs for FlatArrayCheck
• 2d330b1: 8384193: [lworld] Remove identity field from java.lang.Class
• ... and 8 more: https://git.openjdk.org/valhalla/compare/632b1bd6b14d1627aca9b1983c4d2a7fe00d8382...lworld

As there are no conflicts, your changes will automatically be rebased on top of these commits when integrating. If you prefer to avoid this automatic rebasing, please check the documentation for the /integrate command for further details.

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

[mlbridge]

Webrevs

• 00: Full (35422ac5)

[liach]

Looks fine to me. I can update serialization implementation to reject writing value objects with serialization.

[dansmithcode]

Yes, @liach, that was my next step: see if you can review the implementation and fix up any divergence from the spec. Thanks!

[dansmithcode]

/integrate

[openjdk]

Going to push as commit 4824ac0.
Since your change was applied there have been 12 commits pushed to the lworld branch:

• cc40808: 8384105: [lworld] serviceability/jvmti/valhalla/SampledObjectAllocValue/SampledObjectAllocValue.java fails after JDK-8382702
• 6b9eb7d: 8384283: [lworld] Post-parse call devirtualization with unloaded return type fails
• de6aff4: 8384364: [lworld] C2: assert(cloned_flat_array_check->req() == 3) failed: unexpected number of inputs for FlatArrayCheck
• ... and 9 more: https://git.openjdk.org/valhalla/compare/632b1bd6b14d1627aca9b1983c4d2a7fe00d8382...lworld

Your commit was automatically rebased without conflicts.

[openjdk]

@dansmithcode Pushed as commit 4824ac0.

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