< prev index next >

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

Print this page 
*** 30,10 ***
--- 30,12 ---
  <body>
  <h1 id="ValueBased">{@index "Value-based Classes"}</h1>
  
  Some classes, such as {@code java.lang.Integer} and
  {@code java.time.LocalDate}, are <em>value-based</em>.
+ The compiler and runtime enforce the value based properties below if it is declared
+ as {@code value class} and preview features are enabled.
  A value-based class has the following properties:
  <ul>
      <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 hashCode},

*** 50,12 ***
          a unique identity on each method call&mdash;in particular, any factory
          method's contract must allow for the possibility that if two independently-produced
          instances are equal according to {@code equals()}, they may also be
          equal according to {@code ==};</li>
      <li>the class is final, and extends either {@code Object} or a hierarchy of
!         abstract classes that declare no instance fields or instance initializers
-         and whose constructors are empty.</li>
  </ul>
  
  <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 {@code ==} or indirectly via an appeal to synchronization, identity hashing,
--- 52,11 ---
          a unique identity on each method call&mdash;in particular, any factory
          method's contract must allow for the possibility that if two independently-produced
          instances are equal according to {@code equals()}, they may also be
          equal according to {@code ==};</li>
      <li>the class is final, and extends either {@code Object} or a hierarchy of
!         abstract value classes.</li>
  </ul>
  
  <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 {@code ==} or indirectly via an appeal to synchronization, identity hashing,

*** 63,10 ***
  
  <p>Synchronization on instances of value-based classes is strongly discouraged,
      because the programmer cannot guarantee exclusive ownership of the
      associated monitor.</p>
  
! <p>Identity-related behavior of value-based classes may change in a future release.
!     For example, synchronization may fail.</p>
  
  </body>
  </html>
--- 64,15 ---
  
  <p>Synchronization on instances of value-based classes is strongly discouraged,
      because the programmer cannot guarantee exclusive ownership of the
      associated monitor.</p>
  
! <p>Identity-related behavior of value-based classes may change when implemented as a value class.
! </p>
+ <ul>
+     <li>The class may choose to allocate/cache instances differently.
+     <li>The use of the value class for synchronization or with
+     {@linkplain java.lang.ref.Reference object references} result in {@link IdentityException}.
+ </ul>
  
  </body>
  </html>
< prev index next >