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.
+