New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
8254275: [valhalla/jep390] Revise "value-based class" & apply to wrappers #222
Changes from all commits
5ae32ad
0b97d4a
2f13d53
3288f43
1448724
3c8fa53
7746462
a327a32
4c21b22
6191412
63db13c
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -31,36 +31,38 @@ | ||
<body> | ||
<h1 id="ValueBased">{@index "Value-based Classes"}</h1> | ||
|
||
Some classes, such as <code>java.util.Optional</code> and | ||
<code>java.time.LocalDateTime</code>, are <em>value-based</em>. Instances of a | ||
value-based class: | ||
Some classes, such as <code>java.lang.Integer</code> and | ||
<code>java.time.LocalDate</code>, are <em>value-based</em>. | ||
A value-based class has the following properties: | ||
<ul> | ||
<li>are final and immutable (though may contain references to mutable | ||
objects);</li> | ||
<li>have implementations of <code>equals</code>, | ||
<code>hashCode</code>, and <code>toString</code> which are computed | ||
solely from the instance's state and not from its identity or the state | ||
of any other object or variable;</li> | ||
<li>make no use of identity-sensitive operations such as reference | ||
equality (<code>==</code>) between instances, identity hash code of | ||
instances, or synchronization on an instances's intrinsic lock;</li> | ||
<li>are considered equal solely based on <code>equals()</code>, not | ||
based on reference equality (<code>==</code>);</li> | ||
<li>do not have accessible constructors, but are instead instantiated | ||
through factory methods which make no commitment as to the identity | ||
of returned instances;</li> | ||
<li>are <em>freely substitutable</em> when equal, meaning that interchanging | ||
any two instances <code>x</code> and <code>y</code> that are equal | ||
according to <code>equals()</code> in any computation or method | ||
invocation should produce no visible change in behavior. | ||
</li> | ||
<li>the class declares only final instance fields (though these may contain references | ||
to mutable objects);</li> | ||
<li>the class's implementations of <code>equals</code>, <code>hashCode</code>, | ||
and <code>toString</code> compute their results solely from the values | ||
of the class's instance fields (and the members of the objects they | ||
reference), not from the instance's identity;</li> | ||
<li>the class's methods treat instances as <em>freely substitutable</em> | ||
when equal, meaning that interchanging any two instances <code>x</code> and | ||
<code>y</code> that are equal according to <code>equals()</code> produces no | ||
visible change in the behavior of the class's methods;</li> | ||
<li>the class performs no synchronization using an instance's monitor;</li> | ||
<li>the class does not declare (or has deprecated any) accessible constructors;</li> | ||
<li>the class does not provide any instance creation mechanism that promises | ||
a unique identity on each method call—in particular, any factory | ||
method's contract must allow for the possibility that if two independently-produced | ||
instances are equal according to <code>equals()</code>, they may also be | ||
equal according to <code>==</code>;</li> | ||
<li>the class is final, and extends either <code>Object</code> or a hierarchy of | ||
abstract classes that declare no instance fields or instance initializers | ||
and whose constructors are empty.</li> | ||
</ul> | ||
|
||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Perhaps as an intro to the following points to make it clear these are about what a program should and should not do. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. These two paragraphs are fine, they express the negative, not what a developer should do. |
||
<p>A program may produce unpredictable results if it attempts to distinguish two | ||
references to equal values of a value-based class, whether directly via reference | ||
<p>When two instances of a value-based class are equal (according to `equals`), a program | ||
should not attempt to distinguish between their identities, whether directly via reference | ||
equality or indirectly via an appeal to synchronization, identity hashing, | ||
serialization, or any other identity-sensitive mechanism. Use of such | ||
identity-sensitive operations on instances of value-based classes may have | ||
unpredictable effects and should be avoided.</p> | ||
serialization, or any other identity-sensitive mechanism.</p> | ||
<p>Synchronization on instances of value-based classes is strongly discouraged, | ||
because the programmer cannot guarantee exclusive ownership of the | ||
associated monitor.</p> | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Duplicates the requirements in the bullet list.
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. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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 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 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. |
||
</body> | ||
</html> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The mdash came out as "â" in the javadoc.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hmm. That's annoying. In what context? Worked okay when I did a
make docs
...Are character entities supposed to work? Or is the coding convention to stick strictly to ASCII?