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 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 hashCode},
40 and {@code toString} 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} and
45 {@code y} that are equal according to {@code equals()} 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 discourages use of) 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()}, they may also be
53 equal according to {@code ==};</li>
54 <li>the class is final, and extends either {@code Object} 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 {@code ==} 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>
|
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>
|