src/java.base/share/classes/java/lang/Boolean.java

@@ -1,7 +1,7 @@
  /*
-  * Copyright (c) 1994, 2025, Oracle and/or its affiliates. All rights reserved.
+  * Copyright (c) 1994, 2026, Oracle and/or its affiliates. All rights reserved.
   * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   *
   * This code is free software; you can redistribute it and/or modify it
   * under the terms of the GNU General Public License version 2 only, as
   * published by the Free Software Foundation.  Oracle designates this

@@ -23,10 +23,11 @@
   * questions.
   */
  
  package java.lang;
  
+ import jdk.internal.value.DeserializeConstructor;
  import jdk.internal.vm.annotation.IntrinsicCandidate;
  
  import java.lang.constant.Constable;
  import java.lang.constant.ConstantDescs;
  import java.lang.constant.DynamicConstantDesc;

@@ -43,18 +44,27 @@
   * {@code String} to a {@code boolean}, as well as other
   * constants and methods useful when dealing with a
   * {@code boolean}.
   *
   * <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.
+  * 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 Boolean} 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>
   *
   * @author  Arthur van Hoff
   * @since   1.0
   */
+ @jdk.internal.MigratedValueClass
  @jdk.internal.ValueBased
  public final class Boolean implements java.io.Serializable,
                                        Comparable<Boolean>, Constable
  {
      /**

@@ -99,10 +109,11 @@
       * likely to yield significantly better space and time performance.
       * Also consider using the final fields {@link #TRUE} and {@link #FALSE}
       * if possible.
       */
      @Deprecated(since="9")
+     @DeserializeConstructor
      public Boolean(boolean value) {
          this.value = value;
      }
  
      /**

@@ -155,17 +166,30 @@
          return value;
      }
  
      /**
       * Returns a {@code Boolean} instance representing the specified
-      * {@code boolean} value.  If the specified {@code boolean} value
-      * is {@code true}, this method returns {@code Boolean.TRUE};
-      * if it is {@code false}, this method returns {@code Boolean.FALSE}.
-      * If a new {@code Boolean} instance is not required, this method
-      * should generally be used in preference to the constructor
-      * {@link #Boolean(boolean)}, as this method is likely to yield
-      * significantly better space and time performance.
+      * {@code boolean} value.
+      * <div class="preview-block">
+      *      <div class="preview-comment">
+      *          <p>
+      *              - When preview features are NOT enabled, {@code Boolean} is an identity class.
+      *              If the specified {@code boolean} value is {@code true},
+      *              this method returns {@code Boolean.TRUE}; if it is
+      *              {@code false}, this method returns {@code Boolean.FALSE}.
+      *              If a new {@code Boolean} instance is not required, this
+      *              method should generally be used in preference to the
+      *              constructor {@link #Boolean(boolean)}, as this method is
+      *              likely to yield significantly better space and time
+      *              performance.
+      *          </p>
+      *          <p>
+      *              - When preview features are enabled, {@code Boolean} is a {@linkplain Class#isValue value class}.
+      *              The {@code valueOf} behavior is the same as invoking the constructor.
+      *          </p>
+      *      </div>
+      * </div>
       *
       * @param  b a boolean value.
       * @return a {@code Boolean} instance representing {@code b}.
       * @since  1.4
       */