RFR: 8254275: [valhalla/jep390] Revise "value-based class" & apply to wrappers [v4]

[Dan Smith]

On Mon, 2 Nov 2020 19:48:57 GMT, Roger Riggs <rriggs at openjdk.org> wrote:

>> Dan Smith has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Addressing additional review comments for ValueBased.html
>
> src/java.base/share/classes/java/lang/doc-files/ValueBased.html line 50:
> 
>> 48:     <li>the class performs no synchronization using an instance's monitor;</li>
>> 49:     <li>the class does not declare (or has deprecated any) accessible constructors;</li>
>> 50:     <li>the class does not provide any other instance creation mechanism that promises
> 
> The "other" in "any other" is unnecessary.  
> `The class does not provide any instance creation mechanism that promises a unique identity.`
> <full stop>
> I don't know that the second part means in practice.  What does 'allow for the possibility', apply to?
> It seems apply to the factory method. Is there an example where the factory method needs to take some particular action or make some condition true?  If two instances are `==` then it is more likely that other methods would be interested in that, not the factory method.

Agree, I can drop "other".

The intent is that there's a restriction on a factory method's *contract*. I can make that explicit: "any factory method's contract must allow for the possibility..."

> src/java.base/share/classes/java/lang/doc-files/ValueBased.html line 60:
> 
>> 58:     <li>
>> 59: </ul>
>> 60: 
> 
> Perhaps as an intro to the following points to make it clear these are about what a program should and should not do.
> Should use equals(); should use explicit synchronization using lock objects or instances that are not value-based classes, etc.
> `Programs should not attempt to distinguish the identities of value based class instances, otherwise the result may be unpredictable.`

I'm not totally following. This is a revision to the "When two instances" paragraph? Can you propose an alternative phrasing for the entire paragraph?

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

PR: https://git.openjdk.java.net/valhalla/pull/222