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

[Dan Smith]

On Fri, 16 Oct 2020 21:07:09 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 review comments in ValueBased.html
>
> 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.

I'll revise to clarify that the bulleted list is about properties of the class declaration, while the subsequent
sentences are constraints on/advice to clients. (Is there a better way to talk about clients than "a program should
not..."? "Programmer", "client", "user" all kind of work, but I don't love any of them...) With that distinction in
mind, I don't think the client stuff works very well until we first define what we mean by "value-based class".

I did remove what seemed to me like a redundant bullet from the original list (see my earlier comment). With what's
left, each one is trying to say something distinct, although maybe some rephrasing in certain places could help.

The `final` class and field restrictions were combined before, but I split them because they're two very different
constraints—one about extension, the other about immutability. (It's not ideal that Java uses the same keyword for both
properties.) Actually, though, it works pretty well to combine the final class restriction with the superclass
restriction, leaving one bullet all about subclassing. I'll do that.

The bullets that talk about equality are saying 1) the class needs an appropriate equals/hashCode/toString; 2) the
class's instance methods don't have distinct behaviors for instances that are `equals`; 3) the class's factories do not
promise distinct identities for instances that are `equals`. Those are three distinct things to say; I'm not seeing a
clear way to combine them.

Synchronization: forget primitive classes. This is advice to current clients of value-based classes. And the advice is:
don't synchronize, because you can't be sure someone else isn't doing the same on the same object. This is advice that
is relevant to current clients without asking them to imagine a future in which the Object & monitor model has changed.
Yet the implication is the same: don't do it.

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

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