From e0270e7e2327cb978f1aecb88e8da39949198a11 Mon Sep 17 00:00:00 2001 From: Dan Smith Date: Fri, 4 Dec 2020 13:36:27 -0700 Subject: [PATCH] 8257776: [valhalla:jep390] Add disclaimer about future changes to value-based classes --- src/java.base/share/classes/java/lang/Boolean.java | 2 +- src/java.base/share/classes/java/lang/Byte.java | 2 +- src/java.base/share/classes/java/lang/Character.java | 2 +- src/java.base/share/classes/java/lang/Double.java | 2 +- src/java.base/share/classes/java/lang/Float.java | 2 +- src/java.base/share/classes/java/lang/Integer.java | 2 +- src/java.base/share/classes/java/lang/Long.java | 2 +- src/java.base/share/classes/java/lang/ProcessHandle.java | 3 ++- src/java.base/share/classes/java/lang/Runtime.java | 2 +- src/java.base/share/classes/java/lang/Short.java | 2 +- .../share/classes/java/lang/doc-files/ValueBased.html | 4 ++++ src/java.base/share/classes/java/time/Duration.java | 3 ++- src/java.base/share/classes/java/time/Instant.java | 3 ++- src/java.base/share/classes/java/time/LocalDate.java | 3 ++- src/java.base/share/classes/java/time/LocalDateTime.java | 3 ++- src/java.base/share/classes/java/time/LocalTime.java | 3 ++- src/java.base/share/classes/java/time/MonthDay.java | 3 ++- src/java.base/share/classes/java/time/OffsetDateTime.java | 3 ++- src/java.base/share/classes/java/time/OffsetTime.java | 3 ++- src/java.base/share/classes/java/time/Period.java | 3 ++- src/java.base/share/classes/java/time/Year.java | 3 ++- src/java.base/share/classes/java/time/YearMonth.java | 3 ++- src/java.base/share/classes/java/time/ZoneId.java | 3 ++- src/java.base/share/classes/java/time/ZoneOffset.java | 3 ++- src/java.base/share/classes/java/time/ZonedDateTime.java | 3 ++- .../share/classes/java/time/chrono/HijrahDate.java | 3 ++- .../share/classes/java/time/chrono/JapaneseDate.java | 3 ++- .../share/classes/java/time/chrono/MinguoDate.java | 3 ++- .../share/classes/java/time/chrono/ThaiBuddhistDate.java | 3 ++- src/java.base/share/classes/java/util/KeyValueHolder.java | 2 +- src/java.base/share/classes/java/util/List.java | 5 +++-- src/java.base/share/classes/java/util/Map.java | 6 ++++-- src/java.base/share/classes/java/util/Optional.java | 2 +- src/java.base/share/classes/java/util/OptionalDouble.java | 2 +- src/java.base/share/classes/java/util/OptionalInt.java | 2 +- src/java.base/share/classes/java/util/OptionalLong.java | 2 +- src/java.base/share/classes/java/util/Set.java | 3 ++- .../share/classes/jdk/incubator/foreign/GroupLayout.java | 3 ++- .../share/classes/jdk/incubator/foreign/MemoryAddress.java | 4 ++-- .../share/classes/jdk/incubator/foreign/MemoryLayout.java | 4 ++-- .../share/classes/jdk/incubator/foreign/MemorySegment.java | 4 ++-- .../share/classes/jdk/incubator/foreign/PaddingLayout.java | 3 ++- .../share/classes/jdk/incubator/foreign/SequenceLayout.java | 3 ++- .../share/classes/jdk/incubator/foreign/ValueLayout.java | 3 ++- test/lib/jdk/test/lib/hexdump/HexPrinter.java | 3 ++- 45 files changed, 81 insertions(+), 49 deletions(-) diff --git a/src/java.base/share/classes/java/lang/Boolean.java b/src/java.base/share/classes/java/lang/Boolean.java index 49b9e556417..79dddc4de4a 100644 --- a/src/java.base/share/classes/java/lang/Boolean.java +++ b/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 diff --git a/src/java.base/share/classes/java/lang/Byte.java b/src/java.base/share/classes/java/lang/Byte.java index c4681bc621e..51e2cf10210 100644 --- a/src/java.base/share/classes/java/lang/Byte.java +++ b/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 diff --git a/src/java.base/share/classes/java/lang/Character.java b/src/java.base/share/classes/java/lang/Character.java index ec736c68d46..1981b24f6b7 100644 --- a/src/java.base/share/classes/java/lang/Character.java +++ b/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 diff --git a/src/java.base/share/classes/java/lang/Double.java b/src/java.base/share/classes/java/lang/Double.java index 3a0eac5c01c..006ccc3837f 100644 --- a/src/java.base/share/classes/java/lang/Double.java +++ b/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 diff --git a/src/java.base/share/classes/java/lang/Float.java b/src/java.base/share/classes/java/lang/Float.java index eac918824ec..c56c35ecaca 100644 --- a/src/java.base/share/classes/java/lang/Float.java +++ b/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 diff --git a/src/java.base/share/classes/java/lang/Integer.java b/src/java.base/share/classes/java/lang/Integer.java index f2a0efb089f..db8c0987d47 100644 --- a/src/java.base/share/classes/java/lang/Integer.java +++ b/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. * *

Implementation note: The implementations of the "bit twiddling" * methods (such as {@link #highestOneBit(int) highestOneBit} and diff --git a/src/java.base/share/classes/java/lang/Long.java b/src/java.base/share/classes/java/lang/Long.java index 24c3dd2c08b..576038873b0 100644 --- a/src/java.base/share/classes/java/lang/Long.java +++ b/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. * *

Implementation note: The implementations of the "bit twiddling" * methods (such as {@link #highestOneBit(long) highestOneBit} and diff --git a/src/java.base/share/classes/java/lang/ProcessHandle.java b/src/java.base/share/classes/java/lang/ProcessHandle.java index 68d1ff0026d..561e713c868 100644 --- a/src/java.base/share/classes/java/lang/ProcessHandle.java +++ b/src/java.base/share/classes/java/lang/ProcessHandle.java @@ -83,7 +83,8 @@ * value-based, * 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. * diff --git a/src/java.base/share/classes/java/lang/Runtime.java b/src/java.base/share/classes/java/lang/Runtime.java index 5c166ec5a1e..84e41e6c8ff 100644 --- a/src/java.base/share/classes/java/lang/Runtime.java +++ b/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.

+ * occur, including identity-related changes in a future release.

* * @since 9 */ diff --git a/src/java.base/share/classes/java/lang/Short.java b/src/java.base/share/classes/java/lang/Short.java index 57d1dc0c0ec..fb536c936b8 100644 --- a/src/java.base/share/classes/java/lang/Short.java +++ b/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 diff --git a/src/java.base/share/classes/java/lang/doc-files/ValueBased.html b/src/java.base/share/classes/java/lang/doc-files/ValueBased.html index 3c4cd1f4b7d..431838036ce 100644 --- a/src/java.base/share/classes/java/lang/doc-files/ValueBased.html +++ b/src/java.base/share/classes/java/lang/doc-files/ValueBased.html @@ -61,8 +61,12 @@

{@index "Value-based Classes"}

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.

+

Synchronization on instances of value-based classes is strongly discouraged, because the programmer cannot guarantee exclusive ownership of the associated monitor.

+ +

Identity-related behavior of value-based classes may change in a future release.

+ diff --git a/src/java.base/share/classes/java/time/Duration.java b/src/java.base/share/classes/java/time/Duration.java index baecb9e8e4c..c007a73f0f0 100644 --- a/src/java.base/share/classes/java/time/Duration.java +++ b/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. diff --git a/src/java.base/share/classes/java/time/Instant.java b/src/java.base/share/classes/java/time/Instant.java index a59f9857104..f5ec60bde16 100644 --- a/src/java.base/share/classes/java/time/Instant.java +++ b/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. diff --git a/src/java.base/share/classes/java/time/LocalDate.java b/src/java.base/share/classes/java/time/LocalDate.java index a5d9f9e0bd3..27b98d57c9c 100644 --- a/src/java.base/share/classes/java/time/LocalDate.java +++ b/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. diff --git a/src/java.base/share/classes/java/time/LocalDateTime.java b/src/java.base/share/classes/java/time/LocalDateTime.java index 38a59e99e49..01a811b4fb0 100644 --- a/src/java.base/share/classes/java/time/LocalDateTime.java +++ b/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. diff --git a/src/java.base/share/classes/java/time/LocalTime.java b/src/java.base/share/classes/java/time/LocalTime.java index 8983e48ec8b..0923bea030f 100644 --- a/src/java.base/share/classes/java/time/LocalTime.java +++ b/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. diff --git a/src/java.base/share/classes/java/time/MonthDay.java b/src/java.base/share/classes/java/time/MonthDay.java index 5dfcbec7ecb..ea1ee90dd4a 100644 --- a/src/java.base/share/classes/java/time/MonthDay.java +++ b/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. diff --git a/src/java.base/share/classes/java/time/OffsetDateTime.java b/src/java.base/share/classes/java/time/OffsetDateTime.java index c1fa78d5e41..dd103056101 100644 --- a/src/java.base/share/classes/java/time/OffsetDateTime.java +++ b/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. diff --git a/src/java.base/share/classes/java/time/OffsetTime.java b/src/java.base/share/classes/java/time/OffsetTime.java index 36ba793bb83..7112bf7f02e 100644 --- a/src/java.base/share/classes/java/time/OffsetTime.java +++ b/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. diff --git a/src/java.base/share/classes/java/time/Period.java b/src/java.base/share/classes/java/time/Period.java index 673c48fb560..3d334b88cb0 100644 --- a/src/java.base/share/classes/java/time/Period.java +++ b/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. diff --git a/src/java.base/share/classes/java/time/Year.java b/src/java.base/share/classes/java/time/Year.java index 4082e180024..92720fd0348 100644 --- a/src/java.base/share/classes/java/time/Year.java +++ b/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. diff --git a/src/java.base/share/classes/java/time/YearMonth.java b/src/java.base/share/classes/java/time/YearMonth.java index f0f99b65dca..bde8d3d3aa3 100644 --- a/src/java.base/share/classes/java/time/YearMonth.java +++ b/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. diff --git a/src/java.base/share/classes/java/time/ZoneId.java b/src/java.base/share/classes/java/time/ZoneId.java index 1c7d8f95037..e6d6db69ebc 100644 --- a/src/java.base/share/classes/java/time/ZoneId.java +++ b/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. diff --git a/src/java.base/share/classes/java/time/ZoneOffset.java b/src/java.base/share/classes/java/time/ZoneOffset.java index 36cbee8d24b..f97d5a7ba32 100644 --- a/src/java.base/share/classes/java/time/ZoneOffset.java +++ b/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. diff --git a/src/java.base/share/classes/java/time/ZonedDateTime.java b/src/java.base/share/classes/java/time/ZonedDateTime.java index 151d414f56e..3edbd6ef544 100644 --- a/src/java.base/share/classes/java/time/ZonedDateTime.java +++ b/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, diff --git a/src/java.base/share/classes/java/time/chrono/HijrahDate.java b/src/java.base/share/classes/java/time/chrono/HijrahDate.java index fc77c9d1d06..a88fd863f7f 100644 --- a/src/java.base/share/classes/java/time/chrono/HijrahDate.java +++ b/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. diff --git a/src/java.base/share/classes/java/time/chrono/JapaneseDate.java b/src/java.base/share/classes/java/time/chrono/JapaneseDate.java index 3699933e419..9272746b5a2 100644 --- a/src/java.base/share/classes/java/time/chrono/JapaneseDate.java +++ b/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. diff --git a/src/java.base/share/classes/java/time/chrono/MinguoDate.java b/src/java.base/share/classes/java/time/chrono/MinguoDate.java index 70ad47b6291..b59215340ff 100644 --- a/src/java.base/share/classes/java/time/chrono/MinguoDate.java +++ b/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. diff --git a/src/java.base/share/classes/java/time/chrono/ThaiBuddhistDate.java b/src/java.base/share/classes/java/time/chrono/ThaiBuddhistDate.java index 5153c0a672e..57581780fde 100644 --- a/src/java.base/share/classes/java/time/chrono/ThaiBuddhistDate.java +++ b/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. diff --git a/src/java.base/share/classes/java/util/KeyValueHolder.java b/src/java.base/share/classes/java/util/KeyValueHolder.java index d0b91a6b49b..4255ee46750 100644 --- a/src/java.base/share/classes/java/util/KeyValueHolder.java +++ b/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 diff --git a/src/java.base/share/classes/java/util/List.java b/src/java.base/share/classes/java/util/List.java index 8392b4f6a23..22528f49736 100644 --- a/src/java.base/share/classes/java/util/List.java +++ b/src/java.base/share/classes/java/util/List.java @@ -109,8 +109,9 @@ *
  • They are value-based. * 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. *
  • They are serialized as specified on the * Serialized Form diff --git a/src/java.base/share/classes/java/util/Map.java b/src/java.base/share/classes/java/util/Map.java index 6063af06f2c..6a1fbf1ee91 100644 --- a/src/java.base/share/classes/java/util/Map.java +++ b/src/java.base/share/classes/java/util/Map.java @@ -133,7 +133,8 @@ *
  • They are value-based. * 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. *
  • They are serialized as specified on the @@ -1639,7 +1640,8 @@ static Map ofEntries(Entry... entries) { *
  • They are value-based. * 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. * diff --git a/src/java.base/share/classes/java/util/Optional.java b/src/java.base/share/classes/java/util/Optional.java index b3870cfb17d..dcb7773e0b1 100644 --- a/src/java.base/share/classes/java/util/Optional.java +++ b/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 diff --git a/src/java.base/share/classes/java/util/OptionalDouble.java b/src/java.base/share/classes/java/util/OptionalDouble.java index 285ca83d733..ef3539ad984 100644 --- a/src/java.base/share/classes/java/util/OptionalDouble.java +++ b/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 diff --git a/src/java.base/share/classes/java/util/OptionalInt.java b/src/java.base/share/classes/java/util/OptionalInt.java index 471cf5c1fea..8431223517d 100644 --- a/src/java.base/share/classes/java/util/OptionalInt.java +++ b/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 diff --git a/src/java.base/share/classes/java/util/OptionalLong.java b/src/java.base/share/classes/java/util/OptionalLong.java index 1cb92719771..90e2b89a392 100644 --- a/src/java.base/share/classes/java/util/OptionalLong.java +++ b/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 diff --git a/src/java.base/share/classes/java/util/Set.java b/src/java.base/share/classes/java/util/Set.java index fd2d002ad6a..5589e41ec97 100644 --- a/src/java.base/share/classes/java/util/Set.java +++ b/src/java.base/share/classes/java/util/Set.java @@ -84,7 +84,8 @@ *
  • They are value-based. * 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. *
  • They are serialized as specified on the diff --git a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/GroupLayout.java b/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/GroupLayout.java index 65165ec625f..c506c1476a9 100644 --- a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/GroupLayout.java +++ b/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. diff --git a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemoryAddress.java b/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemoryAddress.java index 8fa5b4784b8..67d55940f34 100644 --- a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemoryAddress.java +++ b/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemoryAddress.java @@ -41,8 +41,8 @@ *

    * All implementations of this interface must be value-based; * 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. *

    * Non-platform classes should not implement {@linkplain MemoryAddress} directly. * diff --git a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemoryLayout.java b/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemoryLayout.java index 5206e27cb98..800325ec8a7 100644 --- a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemoryLayout.java +++ b/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemoryLayout.java @@ -77,8 +77,8 @@ *

    * All implementations of this interface must be value-based; * 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. *

    * Non-platform classes should not implement {@linkplain MemoryLayout} directly. * diff --git a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemorySegment.java b/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemorySegment.java index 5c3b7c6738b..b112522bd6f 100644 --- a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemorySegment.java +++ b/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemorySegment.java @@ -51,8 +51,8 @@ *

    * All implementations of this interface must be value-based; * 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. *

    * Non-platform classes should not implement {@linkplain MemorySegment} directly. * diff --git a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/PaddingLayout.java b/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/PaddingLayout.java index 3eaa9b5921f..1b843cb091c 100644 --- a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/PaddingLayout.java +++ b/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/PaddingLayout.java @@ -41,7 +41,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. diff --git a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/SequenceLayout.java b/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/SequenceLayout.java index 1db09352f47..fea4e185430 100644 --- a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/SequenceLayout.java +++ b/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/SequenceLayout.java @@ -58,7 +58,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. diff --git a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/ValueLayout.java b/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/ValueLayout.java index c2082861d14..27b02367ab7 100644 --- a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/ValueLayout.java +++ b/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/ValueLayout.java @@ -43,7 +43,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. diff --git a/test/lib/jdk/test/lib/hexdump/HexPrinter.java b/test/lib/jdk/test/lib/hexdump/HexPrinter.java index f702fabec84..7d915c13aa8 100644 --- a/test/lib/jdk/test/lib/hexdump/HexPrinter.java +++ b/test/lib/jdk/test/lib/hexdump/HexPrinter.java @@ -146,7 +146,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. * *

    * This class is immutable and thread-safe.