13 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
14 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
15 version 2 for more details (a copy is included in the LICENSE file that
16 accompanied this code).
17
18 You should have received a copy of the GNU General Public License version
19 2 along with this work; if not, write to the Free Software Foundation,
20 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
21
22 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
23 or visit www.oracle.com if you need additional information or have any
24 questions.
25 -->
26 <html lang="en">
27 <head>
28 <title>Value-based Classes</title>
29 </head>
30 <body>
31 <h1 id="ValueBased">{@index "Value-based Classes"}</h1>
32
33 Some classes, such as <code>java.lang.Integer</code> and
34 <code>java.time.LocalDate</code>, are <em>value-based</em>.
35 A value-based class has the following properties:
36 <ul>
37 <li>the class declares only final instance fields (though these may contain references
38 to mutable objects);</li>
39 <li>the class's implementations of <code>equals</code>, <code>hashCode</code>,
40 and <code>toString</code> compute their results solely from the values
41 of the class's instance fields (and the members of the objects they
42 reference), not from the instance's identity;</li>
43 <li>the class's methods treat instances as <em>freely substitutable</em>
44 when equal, meaning that interchanging any two instances <code>x</code> and
45 <code>y</code> that are equal according to <code>equals()</code> produces no
46 visible change in the behavior of the class's methods;</li>
47 <li>the class performs no synchronization using an instance's monitor;</li>
48 <li>the class does not declare (or has deprecated any) accessible constructors;</li>
49 <li>the class does not provide any instance creation mechanism that promises
50 a unique identity on each method call—in particular, any factory
51 method's contract must allow for the possibility that if two independently-produced
52 instances are equal according to <code>equals()</code>, they may also be
53 equal according to <code>==</code>;</li>
54 <li>the class is final, and extends either <code>Object</code> or a hierarchy of
55 abstract classes that declare no instance fields or instance initializers
56 and whose constructors are empty.</li>
57 </ul>
58
59 <p>When two instances of a value-based class are equal (according to `equals`), a program
60 should not attempt to distinguish between their identities, whether directly via reference
61 equality or indirectly via an appeal to synchronization, identity hashing,
62 serialization, or any other identity-sensitive mechanism.</p>
63
64 <p>Synchronization on instances of value-based classes is strongly discouraged,
65 because the programmer cannot guarantee exclusive ownership of the
66 associated monitor.</p>
67
68 <p>Identity-related behavior of value-based classes may change in a future release.
69 For example, synchronization may fail.</p>
70
71 </body>
72 </html>
|
13 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
14 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
15 version 2 for more details (a copy is included in the LICENSE file that
16 accompanied this code).
17
18 You should have received a copy of the GNU General Public License version
19 2 along with this work; if not, write to the Free Software Foundation,
20 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
21
22 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
23 or visit www.oracle.com if you need additional information or have any
24 questions.
25 -->
26 <html lang="en">
27 <head>
28 <title>Value-based Classes</title>
29 </head>
30 <body>
31 <h1 id="ValueBased">{@index "Value-based Classes"}</h1>
32
33 Some classes, such as {@code java.lang.Integer} and
34 {@code java.time.LocalDate}, are <em>value-based</em>.
35 The compiler and runtime enforce the value based properties below if it is declared
36 as {@code value class} and preview features are enabled.
37 A value-based class has the following properties:
38 <ul>
39 <li>the class declares only final instance fields (though these may contain references
40 to mutable objects);</li>
41 <li>the class's implementations of {@code equals}, {@code hashCode},
42 and {@code toString} compute their results solely from the values
43 of the class's instance fields (and the members of the objects they
44 reference), not from the instance's identity;</li>
45 <li>the class's methods treat instances as <em>freely substitutable</em>
46 when equal, meaning that interchanging any two instances {@code x} and
47 {@code y} that are equal according to {@code equals()} produces no
48 visible change in the behavior of the class's methods;</li>
49 <li>the class performs no synchronization using an instance's monitor;</li>
50 <li>the class does not declare (or discourages use of) accessible constructors;</li>
51 <li>the class does not provide any instance creation mechanism that promises
52 a unique identity on each method call—in particular, any factory
53 method's contract must allow for the possibility that if two independently-produced
54 instances are equal according to {@code equals()}, they may also be
55 equal according to {@code ==};</li>
56 <li>the class is final, and extends either {@code Object} or a hierarchy of
57 abstract value classes.</li>
58 </ul>
59
60 <p>When two instances of a value-based class are equal (according to `equals`), a program
61 should not attempt to distinguish between their identities, whether directly via reference
62 equality {@code ==} or indirectly via an appeal to synchronization, identity hashing,
63 serialization, or any other identity-sensitive mechanism.</p>
64
65 <p>Synchronization on instances of value-based classes is strongly discouraged,
66 because the programmer cannot guarantee exclusive ownership of the
67 associated monitor.</p>
68
69 <p>Identity-related behavior of value-based classes may change when implemented as a value class.
70 </p>
71 <ul>
72 <li>The class may choose to allocate/cache instances differently.
73 <li>The use of the value class for synchronization or with
74 {@linkplain java.lang.ref.Reference object references} result in {@link IdentityException}.
75 </ul>
76
77 </body>
78 </html>
|