8387417: [lworld] API doc improvements for java.lang.Object

[AlanBateman]

Updates to java.lang.Object API docs:

• Improve preview-comment in class description that defines value class and value object
• Update spec for the finalize method to make it clear when finalize method of a value class is never invoked by the garbage collector
• Update the implSpec for the clone to specify behavior of Object.clone for value objects. Also add paragraph to method description for value objects, and add API note to advise using copy constructors or static factory methods instead
• Improve preview-comment in wait/notify methods and drop confusing addition to IMSE exception

A sanity test is added, this depends on the fix to finalizer registration in pull/2589.

---

• 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-8387417: [lworld] API doc improvements for java.lang.Object (Bug - P4)

Reviewers

• Jaikiran Pai (@jaikiran - no project role)
• Chen Liang (@liach - Committer)

Reviewing

Using git

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

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

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 2588

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

Using diff file

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

Using Webrev

Link to Webrev Comment

[bridgekeeper]

👋 Welcome back alanb! 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]

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

8387417: [lworld] API doc improvements for java.lang.Object

Reviewed-by: jpai, 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 5 new commits pushed to the lworld branch:

• 71eb703: 8386160: [lworld] Post jdk-27+25 compiler/valhalla/inlinetypes/TestIntrinsics.java#id4 assertion
• fa0f4a6: 8387464: [lworld] Increase memlimit and unproblemlist TestValueConstruction.java
• 2ae8e47: 8387454: [lworld] Update Strict fields JEP number
• ... and 2 more: https://git.openjdk.org/valhalla/compare/3a3ac5cf3e6872952a88906b597948215eb769d3...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.

As you do not have Committer status in this project an existing Committer must agree to sponsor your change. Possible candidates are the reviewers of this PR (@liach) but any other Committer may sponsor as well.

➡️ To flag this PR as ready for integration with the above commit message, type /integrate in a new comment. (Afterwards, your sponsor types /sponsor in a new comment to perform the integration).

[mlbridge]

Webrevs

• 01: Full - Incremental (dbc626a1)
• 00: Full (5a280a98)

[jaikiran]

Hello Alan, in several other places in the other JDK, we seem to refer to such classes as concrete value class. Should we do the same here instead of saying non-abstract value class?

[AlanBateman]

Defining a value object as an instance of non-abstract value classes works here, it's similar to the wording in the changes for the JLS.

[liach]

I would prefer to phrase it like "the class of a value object is a value class", more in line with code like o.getClass().isValue().

However, Valhalla models "identity" as the extra thing, so I guess it is better to go like "An identity object is an object whose class is an identity class or an array type. All other objects are value objects."

[AlanBateman]

I would prefer to keep this sentence as proposed as it keeps it consistent with the JLS and keeps the ordering that the terms are introduces consistent with the first sentence. I would be a bit wary of "All other objects are value objects" as it hints that there are other things that are also value classes.

[jaikiran]

Typo - should have been "abstract value class ..."

[AlanBateman]

Well spotted.

[jaikiran]

Thank you for the update. This looks good to me.

[liach]

The introductory paragraph in class spec might be subject to further discussion to introduce people to "identity is the extra thing" view, but that shouldn't be a blocker.