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

[Roger Riggs]

On Fri, 16 Oct 2020 22:51:31 GMT, Dan Smith <dlsmith at openjdk.org> wrote:

>> Polishing the specification of "value-based class" to align with requirements of inline classes, allow classes (like Integer) with deprecated constructors, and clarify expectations for clients.
>> 
>> Full docs build: http://cr.openjdk.java.net/~dlsmith/8254275/8254275-20201013/api/index.html
>
> 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 42:

> 40:     <li>the class declares implementations of <code>equals</code>,
> 41:         <code>hashCode</code>, and <code>toString</code> which are computed
> 42:         solely from the values of the class's instance fields (and properties of

Can the word "properties" be avoided,m here and above? It it a loaded term.  Perhaps attributes?

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.

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.`

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

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