RFR: 8254275: Development to revise "value-based class" & apply to wrappers [v3]

[Roger Riggs]

On Fri, 16 Oct 2020 18:34:33 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 review comments in ValueBased.html

src/java.base/share/classes/java/lang/doc-files/ValueBased.html line 49:

> 47:         the behavior of the class's methods;</li>
> 48:     <li>perform no synchronization using an instance's monitor;</li>
> 49:     <li>do not have (or have deprecated any) accessible constructors;</li>

Having an accessible constructor should not be prohibited.
Constructors do not imply or contradict the other constraints.
And when we get to Valhalla, primitive classes are allowed to have accessible constructors.
At least for the time being, the wrapper classes DO have accessible constructors; if the constraint is retained, then
Integer, etc cannot be value-based.

src/java.base/share/classes/java/lang/doc-files/ValueBased.html line 51:

> 49:     <li>do not have (or have deprecated any) accessible constructors;</li>
> 50:     <li>do not provide any other instance creation mechanism that promises
> 51:         a unique identity on each method call—in particular, any factory

The mdash came out as "â"  in the javadoc.

src/java.base/share/classes/java/lang/doc-files/ValueBased.html line 55:

> 53:         instances are equal according to <code>equals()</code>, they may also be
> 54:         equal according to <code>==</code>;</li>
> 55:     <li>are final;</li>

It might be useful to be able to mark an abstract class as @ValueBased to document that it is part of an intended
ValueBased class hierarchy. Perhaps add "or be abstract".

src/java.base/share/classes/java/lang/doc-files/ValueBased.html line 68:

> 66: <p>Synchronization on instances of value-based classes is strongly discouraged,
> 67:     because the programmer cannot guarantee exclusive ownership of the
> 68:     associated monitor.</p>

Duplicates the requirements in the bullet list.
The bullet list seems too long and the statements are not all orthogonal, making it a bit less clear.
Suggestion:
 - Combine bullet for class is final, with the first bullet requiring final fields.
 - combing the bullets on substitutability and equality, defining substtitutability in terms of the methods.

If the paragraph above is kept, move it to before the bullet list, using the bullet list at the details that explain
the more general understanding of value-based.

The last sentence is still problematic.  For current usage, there is a monitor.
For Valhalla, there is no monitor and it will be a runtime error.  I don't think exclusive ownership comes into it.
And it duplicates an item in the bullet list.

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

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