8257776: [valhalla:jep390] Add disclaimer about future changes to val…

…ue-based classes

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

@@ -52,7 +52,7 @@
  * 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.
+ * occur, including identity-related changes in a future release.
  *
  * @author  Arthur van Hoff
  * @since   1.0

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

@@ -52,7 +52,7 @@
  * 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.
+ * occur, including identity-related changes in a future release.
  *
  * @author  Nakul Saraiya
  * @author  Joseph D. Darcy

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

@@ -126,7 +126,7 @@
  * 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.
+ * occur, including identity-related changes in a future release.
  *
  * @author  Lee Boynton
  * @author  Guy Steele

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

@@ -50,7 +50,7 @@
  * 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.
+ * occur, including identity-related changes in a future release.
  *
  * @author  Lee Boynton
  * @author  Arthur van Hoff

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

@@ -49,7 +49,7 @@
  * 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.
+ * occur, including identity-related changes in a future release.
  *
  * @author  Lee Boynton
  * @author  Arthur van Hoff

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

@@ -54,7 +54,7 @@
  * 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.
+ * occur, including identity-related changes in a future release.
  *
  * <p>Implementation note: The implementations of the "bit twiddling"
  * methods (such as {@link #highestOneBit(int) highestOneBit} and

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

@@ -54,7 +54,7 @@
  * 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.
+ * occur, including identity-related changes in a future release.
  *
  * <p>Implementation note: The implementations of the "bit twiddling"
  * methods (such as {@link #highestOneBit(long) highestOneBit} and

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

@@ -83,7 +83,8 @@
  * <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>,
  * immutable and thread-safe. Programmers should treat instances that are
  * {@linkplain #equals(Object) equal} as interchangeable and should not
- * use instances for synchronization, or unpredictable behavior may occur.
+ * use instances for synchronization, or unpredictable behavior may occur,
+ * including identity-related changes in a future release.
  * Use the {@code equals} or {@link #compareTo(ProcessHandle) compareTo} methods
  * to compare ProcessHandles.
  *

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

@@ -945,7 +945,7 @@ public static Version version() {
      * 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.</p>
+     * occur, including identity-related changes in a future release.</p>
      *
      * @since  9
      */

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

@@ -51,7 +51,7 @@
  * 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.
+ * occur, including identity-related changes in a future release.
  *
  * @author  Nakul Saraiya
  * @author  Joseph D. Darcy

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

@@ -61,8 +61,12 @@ <h1 id="ValueBased">{@index "Value-based Classes"}</h1>
     should not attempt to distinguish between their identities, whether directly via reference
     equality or indirectly via an appeal to synchronization, identity hashing,
     serialization, or any other identity-sensitive mechanism.</p>
+
 <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.</p>
+
 </body>
 </html>

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

@@ -122,7 +122,8 @@
  * 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. The {@code equals} method should be used for comparisons.
+ * occur, including identity-related changes in a future release.
+ * The {@code equals} method should be used for comparisons.
  *
  * @implSpec
  * This class is immutable and thread-safe.

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

@@ -196,7 +196,8 @@
  * 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. The {@code equals} method should be used for comparisons.
+ * occur, including identity-related changes in a future release.
+ * The {@code equals} method should be used for comparisons.
  *
  * @implSpec
  * This class is immutable and thread-safe.

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

@@ -128,7 +128,8 @@
  * 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. The {@code equals} method should be used for comparisons.
+ * occur, including identity-related changes in a future release.
+ * The {@code equals} method should be used for comparisons.
  *
  * @implSpec
  * This class is immutable and thread-safe.

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

@@ -124,7 +124,8 @@
  * 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. The {@code equals} method should be used for comparisons.
+ * occur, including identity-related changes in a future release.
+ * The {@code equals} method should be used for comparisons.
  *
  * @implSpec
  * This class is immutable and thread-safe.

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

@@ -114,7 +114,8 @@
  * 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. The {@code equals} method should be used for comparisons.
+ * occur, including identity-related changes in a future release.
+ * The {@code equals} method should be used for comparisons.
  *
  * @implSpec
  * This class is immutable and thread-safe.

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

@@ -116,7 +116,8 @@
  * 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. The {@code equals} method should be used for comparisons.
+ * occur, including identity-related changes in a future release.
+ * The {@code equals} method should be used for comparisons.
  *
  * @implSpec
  * This class is immutable and thread-safe.

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

@@ -117,7 +117,8 @@
  * 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. The {@code equals} method should be used for comparisons.
+ * occur, including identity-related changes in a future release.
+ * The {@code equals} method should be used for comparisons.
  *
  * @implSpec
  * This class is immutable and thread-safe.

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

@@ -107,7 +107,8 @@
  * 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. The {@code equals} method should be used for comparisons.
+ * occur, including identity-related changes in a future release.
+ * The {@code equals} method should be used for comparisons.
  *
  * @implSpec
  * This class is immutable and thread-safe.

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

@@ -122,7 +122,8 @@
  * 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. The {@code equals} method should be used for comparisons.
+ * occur, including identity-related changes in a future release.
+ * The {@code equals} method should be used for comparisons.
  *
  * @implSpec
  * This class is immutable and thread-safe.

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

@@ -124,7 +124,8 @@
  * 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. The {@code equals} method should be used for comparisons.
+ * occur, including identity-related changes in a future release.
+ * The {@code equals} method should be used for comparisons.
  *
  * @implSpec
  * This class is immutable and thread-safe.

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

@@ -120,7 +120,8 @@
  * 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. The {@code equals} method should be used for comparisons.
+ * occur, including identity-related changes in a future release.
+ * The {@code equals} method should be used for comparisons.
  *
  * @implSpec
  * This class is immutable and thread-safe.

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

@@ -165,7 +165,8 @@
  * 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. The {@code equals} method should be used for comparisons.
+ * occur, including identity-related changes in a future release.
+ * The {@code equals} method should be used for comparisons.
  *
  * @implSpec
  * This abstract class has two implementations, both of which are immutable and thread-safe.

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

@@ -119,7 +119,8 @@
  * 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. The {@code equals} method should be used for comparisons.
+ * occur, including identity-related changes in a future release.
+ * The {@code equals} method should be used for comparisons.
  *
  * @implSpec
  * This class is immutable and thread-safe.

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

@@ -147,7 +147,8 @@
  * 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. The {@code equals} method should be used for comparisons.
+ * occur, including identity-related changes in a future release.
+ * The {@code equals} method should be used for comparisons.
  *
  * @implSpec
  * A {@code ZonedDateTime} holds state equivalent to three separate objects,

src/java.base/share/classes/java/time/chrono/HijrahDate.java

@@ -108,7 +108,8 @@
  * 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. The {@code equals} method should be used for comparisons.
+ * occur, including identity-related changes in a future release.
+ * The {@code equals} method should be used for comparisons.
  *
  * @implSpec
  * This class is immutable and thread-safe.

src/java.base/share/classes/java/time/chrono/JapaneseDate.java

@@ -115,7 +115,8 @@
  * 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. The {@code equals} method should be used for comparisons.
+ * occur, including identity-related changes in a future release.
+ * The {@code equals} method should be used for comparisons.
  *
  * @implSpec
  * This class is immutable and thread-safe.

src/java.base/share/classes/java/time/chrono/MinguoDate.java

@@ -95,7 +95,8 @@
  * 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. The {@code equals} method should be used for comparisons.
+ * occur, including identity-related changes in a future release.
+ * The {@code equals} method should be used for comparisons.
  *
  * @implSpec
  * This class is immutable and thread-safe.

src/java.base/share/classes/java/time/chrono/ThaiBuddhistDate.java

@@ -95,7 +95,8 @@
  * 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. The {@code equals} method should be used for comparisons.
+ * occur, including identity-related changes in a future release.
+ * The {@code equals} method should be used for comparisons.
  *
  * @implSpec
  * This class is immutable and thread-safe.

src/java.base/share/classes/java/util/KeyValueHolder.java

@@ -35,7 +35,7 @@
  * 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.
+ * occur, including identity-related changes in a future release.
  *
  * @apiNote
  * This class is not public. Instances can be created using the

src/java.base/share/classes/java/util/List.java

@@ -109,8 +109,9 @@
  * <li>They are <a href="../lang/doc-files/ValueBased.html">value-based</a>.
  * Programmers should treat instances that are {@linkplain #equals(Object) equal}
  * as interchangeable and should not use them for synchronization, or
- * unpredictable behavior may occur. Callers should make no assumptions
- * about the identity of the returned instances. Factories are free to
+ * unpredictable behavior may occur, including identity-related changes
+ * in a future release. Callers should make no assumptions about the
+ * identity of the returned instances. Factories are free to
  * create new instances or reuse existing ones.
  * <li>They are serialized as specified on the
  * <a href="{@docRoot}/serialized-form.html#java.util.CollSer">Serialized Form</a>

src/java.base/share/classes/java/util/Map.java

@@ -133,7 +133,8 @@
  * <li>They are <a href="../lang/doc-files/ValueBased.html">value-based</a>.
  * Programmers should treat instances that are {@linkplain #equals(Object) equal}
  * as interchangeable and should not use them for synchronization, or
- * unpredictable behavior may occur. Callers should make no assumptions
+ * unpredictable behavior may occur, including identity-related
+ * changes in a future release. Callers should make no assumptions
  * about the identity of the returned instances. Factories are free to
  * create new instances or reuse existing ones.
  * <li>They are serialized as specified on the
@@ -1639,7 +1640,8 @@ static <K, V> Map<K, V> ofEntries(Entry<? extends K, ? extends V>... entries) {
      * <li>They are <a href="../lang/doc-files/ValueBased.html">value-based</a>.
      * Programmers should treat instances that are {@linkplain #equals(Object) equal}
      * as interchangeable and should not use them for synchronization, or
-     * unpredictable behavior may occur. Callers should make no assumptions
+     * unpredictable behavior may occur, including identity-related changes
+     * in a future release. Callers should make no assumptions
      * about the identity of the returned instances. This method is free to
      * create new instances or reuse existing ones.
      * </ul>

src/java.base/share/classes/java/util/Optional.java

@@ -46,7 +46,7 @@
  * 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.
+ * occur, including identity-related changes in a future release.
  *
  * @apiNote
  * {@code Optional} is primarily intended for use as a method return type where

src/java.base/share/classes/java/util/OptionalDouble.java

@@ -45,7 +45,7 @@
  * 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.
+ * occur, including identity-related changes in a future release.
  *
  * @apiNote
  * {@code OptionalDouble} is primarily intended for use as a method return type where

src/java.base/share/classes/java/util/OptionalInt.java

@@ -45,7 +45,7 @@
  * 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.
+ * occur, including identity-related changes in a future release.
  *
  * @apiNote
  * {@code OptionalInt} is primarily intended for use as a method return type where

src/java.base/share/classes/java/util/OptionalLong.java

@@ -45,7 +45,7 @@
  * 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.
+ * occur, including identity-related changes in a future release.
  *
  * @apiNote
  * {@code OptionalLong} is primarily intended for use as a method return type where

src/java.base/share/classes/java/util/Set.java

@@ -84,7 +84,8 @@
  * <li>They are <a href="../lang/doc-files/ValueBased.html">value-based</a>.
  * Programmers should treat instances that are {@linkplain #equals(Object) equal}
  * as interchangeable and should not use them for synchronization, or
- * unpredictable behavior may occur. Callers should make no assumptions
+ * unpredictable behavior may occur, including identity-related
+ * changes in a future release. Callers should make no assumptions
  * about the identity of the returned instances. Factories are free to
  * create new instances or reuse existing ones.
  * <li>They are serialized as specified on the

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/GroupLayout.java

@@ -49,7 +49,8 @@
  * 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. The {@code equals} method should be used for comparisons.
+ * occur, including identity-related changes in a future release.
+ * The {@code equals} method should be used for comparisons.
  *
  * @implSpec
  * This class is immutable and thread-safe.

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemoryAddress.java

@@ -41,8 +41,8 @@
  * <p>
  * All implementations of this interface must be <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>;
  * programmers should treat instances that are {@linkplain #equals(Object) equal} as interchangeable and should not
- * use instances for synchronization, or unpredictable behavior may occur. The {@code equals} method should
- * be used for comparisons.
+ * use instances for synchronization, or unpredictable behavior may occur, including identity-related changes in a future release.
+ * The {@code equals} method should be used for comparisons.
  * <p>
  * Non-platform classes should not implement {@linkplain MemoryAddress} directly.
  *