[lworld] RFR: 8346307: [lworld] Clarify identity vs value in Class, Objects, and document limitations of value objects [v9]

[ExE Boss]

On Wed, 25 Jun 2025 22:05:56 GMT, Roger Riggs <rriggs at openjdk.org> wrote:

>> Add APINote  and javadoc for IdentityException where it will be useful to know that identity or value objects are treated differently. 
>> Simplified WeakHashMap javadoc updates for IdentityException. 
>> Added note to System.identityHashCode to include value objects.
>> Added to class javadoc for IdentityHashMap for value objects.
>
> Roger Riggs has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 16 commits:
> 
>  - A few editorial changes
>    Highlight that in preview-mode, Objects can have either identity or value subclasses.
>  - Merge branch 'lworld' into 8346307-throws-identityexception
>  - Merge branch 'lworld' into 8346307-throws-identityexception
>  - "value interface" is a left over from an earlier design and is not allowed by the JEP 401 JLS.
>    An interface will never have the ACC_IDENTITY modifier, hence 'isValue()' will be true but is not significant.
>    Class.toGenericString() should only include the "value" prefix for record and regular classes.
>    Correct the test to match the toGenericString() output.
>  - Merge branch 'lworld' into 8346307-throws-identityexception
>  - Merge branch 'lworld' into 8346307-throws-identityexception
>  - Merge
>  - Merge branch 'lworld' into 8346307-throws-identityexception
>  - Merge branch 'lworld' into 8346307-throws-identityexception
>  - Merge branch 'lworld' into 8346307-throws-identityexception
>  - ... and 6 more: https://git.openjdk.org/valhalla/compare/81fbc414...6cbade17

src/java.base/share/classes/java/lang/System.java line 477:

> 475:      *      <div class="preview-comment">
> 476:      *          The "identity hash code" of a {@linkplain Class#isValue() value object}
> 477:      *          is computed by combining the hash codes of the value object's fields recursively.

Doesn’t this work by recursively calling the `identityHashCode` algorithm?
Suggestion:

     *          The "identity hash code" of a {@linkplain Class#isValue() value object}
     *          is computed by combining the identity hash codes of the value object's
     *          fields recursively.

-------------

PR Review Comment: https://git.openjdk.org/valhalla/pull/1327#discussion_r2169584484