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

*** 1,7 ***
  /*
!  * Copyright (c) 1994, 2025, Oracle and/or its affiliates. All rights reserved.
   * Copyright (c) 2025, Alibaba Group Holding Limited. 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
--- 1,7 ---
  /*
!  * Copyright (c) 1994, 2026, Oracle and/or its affiliates. All rights reserved.
   * Copyright (c) 2025, Alibaba Group Holding Limited. 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

*** 33,10 ***
--- 33,11 ---
  
  import jdk.internal.math.FloatingDecimal;
  import jdk.internal.math.DoubleConsts;
  import jdk.internal.math.DoubleToDecimal;
  import jdk.internal.util.DecimalDigits;
+ import jdk.internal.value.DeserializeConstructor;
  import jdk.internal.vm.annotation.IntrinsicCandidate;
  
  /**
   * The {@code Double} class is the {@linkplain
   * java.lang##wrapperClass wrapper class} for values of the primitive

*** 48,14 ***
   * {@code String} to a {@code double}, as well as other
   * constants and methods useful when dealing with a
   * {@code double}.
   *
   * <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.
   *
   * <h2><a id=equivalenceRelation>Floating-point Equality, Equivalence,
   * and Comparison</a></h2>
   *
   * IEEE 754 floating-point values include finite nonzero values,
--- 49,22 ---
   * {@code String} to a {@code double}, as well as other
   * constants and methods useful when dealing with a
   * {@code double}.
   *
   * <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 Double} 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>
   *
   * <h2><a id=equivalenceRelation>Floating-point Equality, Equivalence,
   * and Comparison</a></h2>
   *
   * IEEE 754 floating-point values include finite nonzero values,

*** 354,10 ***
--- 363,11 ---
   * @spec https://standards.ieee.org/ieee/754/6210/
   *       IEEE Standard for Floating-Point Arithmetic
   *
   * @since 1.0
   */
+ @jdk.internal.MigratedValueClass
  @jdk.internal.ValueBased
  public final class Double extends Number
          implements Comparable<Double>, Constable, ConstantDesc {
      /**
       * A constant holding the positive infinity of type

*** 956,15 ***
      }
  
      /**
       * Returns a {@code Double} instance representing the specified
       * {@code double} value.
!      * If a new {@code Double} instance is not required, this method
!      * should generally be used in preference to the constructor
!      * {@link #Double(double)}, as this method is likely to yield
!      * significantly better space and time performance by caching
!      * frequently requested values.
       *
       * @param  d a double value.
       * @return a {@code Double} instance representing {@code d}.
       * @since  1.5
       */
--- 966,26 ---
      }
  
      /**
       * Returns a {@code Double} instance representing the specified
       * {@code double} value.
!      * <div class="preview-block">
!      *      <div class="preview-comment">
!      *          <p>
!      *              - When preview features are NOT enabled, {@code Double} is an identity class.
!      *              If a new {@code Double} instance is not required, this
+      *              method should generally be used in preference to the
+      *              constructor {@link #Double(double)}, as this method is
+      *              likely to yield significantly better space and time
+      *              performance by caching frequently requested values.
+      *          </p>
+      *          <p>
+      *              - When preview features are enabled, {@code Double} is a {@linkplain Class#isValue value class}.
+      *              The {@code valueOf} behavior is the same as invoking the constructor.
+      *          </p>
+      *      </div>
+      * </div>
       *
       * @param  d a double value.
       * @return a {@code Double} instance representing {@code d}.
       * @since  1.5
       */

*** 1062,10 ***
--- 1083,11 ---
       * It is rarely appropriate to use this constructor. The static factory
       * {@link #valueOf(double)} is generally a better choice, as it is
       * likely to yield significantly better space and time performance.
       */
      @Deprecated(since="9")
+     @DeserializeConstructor
      public Double(double value) {
          this.value = value;
      }
  
      /**