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

[Chen Liang]

On Tue, 4 Feb 2025 20:59:39 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 incrementally with one additional commit since the last revision:
> 
>   Expand javadoc reference to Reference

Indeed, this API is returning `false` for interfaces and primitive types if preview features are not enabled, which is wrong. Making it simply return `!isIdentity()` may be better and conforms to the javadoc specification here. See https://github.com/openjdk/valhalla/blob/991ec927a2a111e5021b12be3413dfc96efbc74a/src/hotspot/share/prims/jvm.cpp#L1333-L1337

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

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