[lworld] RFR: 8346035: [lworld] javadoc for value objects when enable preview [v2]

[Roger Riggs]

On Fri, 13 Dec 2024 20:51:34 GMT, Dan Smith <dlsmith at openjdk.org> wrote:

>> Roger Riggs has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Tidy up ValueBased.html
>
> src/java.base/share/classes/java/lang/Boolean.java line 51:
> 
>> 49:  * class; programmers should treat instances that are {@linkplain #equals(Object) equal}
>> 50:  * as interchangeable and should not use instances for synchronization, mutexes, or
>> 51:  * with {@linkplain java.lang.ref.Reference object references}.
> 
> We have a preview feature disclaimer for References.
> 
> Is there a similar one for mutexes? (What exactly do you mean by "mutexes"? Is it distinct from "synchronization"?)

Object.wait* and Object.notify are the most obvious APIs to add a disclaimer.
IllegalMonitorStateException is thrown with the class name.  
IdentityException might be preferred and easier for developers to diagnose.

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

PR Review Comment: https://git.openjdk.org/valhalla/pull/1316#discussion_r1887168065