src/java.base/share/classes/java/time/ZonedDateTime.java

*** 142,15 ***
   * of a {@code LocalDateTime} and a {@code ZoneId}. The {@code ZoneOffset} is
   * a vital, but secondary, piece of information, used to ensure that the class
   * represents an instant, especially during a daylight savings overlap.
   * <p>
   * This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
!  * class; programmers should treat instances that are
!  * {@linkplain #equals(Object) equal} as interchangeable and should not
!  * use instances for synchronization, or unpredictable behavior may
!  * occur. For example, in a future release, synchronization may fail.
!  * The {@code equals} method should be used for comparisons.
   *
   * @implSpec
   * A {@code ZonedDateTime} holds state equivalent to three separate objects,
   * a {@code LocalDateTime}, a {@code ZoneId} and the resolved {@code ZoneOffset}.
   * The offset and local date-time are used to define an instant when necessary.
--- 142,22 ---
   * of a {@code LocalDateTime} and a {@code ZoneId}. The {@code ZoneOffset} is
   * a vital, but secondary, piece of information, used to ensure that the class
   * represents an instant, especially during a daylight savings overlap.
   * <p>
   * This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
!  * class; programmers should treat instances that are {@linkplain #equals(Object) equal}
!  * as interchangeable and should not use instances for synchronization, mutexes, or
!  * with {@linkplain java.lang.ref.Reference object references}.
!  *
!  * <div class="preview-block">
+  *      <div class="preview-comment">
+  *          When preview features are enabled, {@code ZonedDateTime} is a {@linkplain Class#isValue value class}.
+  *          Use of value class instances for synchronization, mutexes, or with
+  *          {@linkplain java.lang.ref.Reference object references} result in
+  *          {@link IdentityException}.
+  *      </div>
+  * </div>
   *
   * @implSpec
   * A {@code ZonedDateTime} holds state equivalent to three separate objects,
   * a {@code LocalDateTime}, a {@code ZoneId} and the resolved {@code ZoneOffset}.
   * The offset and local date-time are used to define an instant when necessary.

*** 160,10 ***
--- 167,11 ---
   * This class is immutable and thread-safe.
   *
   * @since 1.8
   */
  @jdk.internal.ValueBased
+ @jdk.internal.MigratedValueClass
  public final class ZonedDateTime
          implements Temporal, ChronoZonedDateTime<LocalDate>, Serializable {
  
      /**
       * Serialization version.