Skip to content
Permalink
Browse files
8257776: [valhalla:jep390] Add disclaimer about future changes to val…
…ue-based classes

Reviewed-by: mchung, rriggs
  • Loading branch information
Dan Smith committed Dec 4, 2020
1 parent cdaf144 commit 54ba37beb57fb60e920aaa4f3308de18e31d6375
Showing with 81 additions and 48 deletions.
  1. +1 −1 src/java.base/share/classes/java/lang/Boolean.java
  2. +1 −1 src/java.base/share/classes/java/lang/Byte.java
  3. +1 −1 src/java.base/share/classes/java/lang/Character.java
  4. +1 −1 src/java.base/share/classes/java/lang/Double.java
  5. +1 −1 src/java.base/share/classes/java/lang/Float.java
  6. +1 −1 src/java.base/share/classes/java/lang/Integer.java
  7. +1 −1 src/java.base/share/classes/java/lang/Long.java
  8. +1 −0 src/java.base/share/classes/java/lang/ProcessHandle.java
  9. +1 −1 src/java.base/share/classes/java/lang/Runtime.java
  10. +1 −1 src/java.base/share/classes/java/lang/Short.java
  11. +5 −0 src/java.base/share/classes/java/lang/doc-files/ValueBased.html
  12. +2 −1 src/java.base/share/classes/java/time/Duration.java
  13. +2 −1 src/java.base/share/classes/java/time/Instant.java
  14. +2 −1 src/java.base/share/classes/java/time/LocalDate.java
  15. +2 −1 src/java.base/share/classes/java/time/LocalDateTime.java
  16. +2 −1 src/java.base/share/classes/java/time/LocalTime.java
  17. +2 −1 src/java.base/share/classes/java/time/MonthDay.java
  18. +2 −1 src/java.base/share/classes/java/time/OffsetDateTime.java
  19. +2 −1 src/java.base/share/classes/java/time/OffsetTime.java
  20. +2 −1 src/java.base/share/classes/java/time/Period.java
  21. +2 −1 src/java.base/share/classes/java/time/Year.java
  22. +2 −1 src/java.base/share/classes/java/time/YearMonth.java
  23. +2 −1 src/java.base/share/classes/java/time/ZoneId.java
  24. +2 −1 src/java.base/share/classes/java/time/ZoneOffset.java
  25. +2 −1 src/java.base/share/classes/java/time/ZonedDateTime.java
  26. +2 −1 src/java.base/share/classes/java/time/chrono/HijrahDate.java
  27. +2 −1 src/java.base/share/classes/java/time/chrono/JapaneseDate.java
  28. +2 −1 src/java.base/share/classes/java/time/chrono/MinguoDate.java
  29. +2 −1 src/java.base/share/classes/java/time/chrono/ThaiBuddhistDate.java
  30. +1 −1 src/java.base/share/classes/java/util/KeyValueHolder.java
  31. +3 −2 src/java.base/share/classes/java/util/List.java
  32. +4 −2 src/java.base/share/classes/java/util/Map.java
  33. +1 −1 src/java.base/share/classes/java/util/Optional.java
  34. +1 −1 src/java.base/share/classes/java/util/OptionalDouble.java
  35. +1 −1 src/java.base/share/classes/java/util/OptionalInt.java
  36. +1 −1 src/java.base/share/classes/java/util/OptionalLong.java
  37. +2 −1 src/java.base/share/classes/java/util/Set.java
  38. +2 −1 src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/GroupLayout.java
  39. +2 −2 src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemoryAddress.java
  40. +2 −2 src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemoryLayout.java
  41. +2 −2 src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemorySegment.java
  42. +2 −1 src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/PaddingLayout.java
  43. +2 −1 src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/SequenceLayout.java
  44. +2 −1 src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/ValueLayout.java
  45. +2 −1 test/lib/jdk/test/lib/hexdump/HexPrinter.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. For example, in a future release, synchronization may fail.
*
* @author Arthur van Hoff
* @since 1.0
@@ -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. For example, in a future release, synchronization may fail.
*
* @author Nakul Saraiya
* @author Joseph D. Darcy
@@ -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. For example, in a future release, synchronization may fail.
*
* @author Lee Boynton
* @author Guy Steele
@@ -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. For example, in a future release, synchronization may fail.
*
* @author Lee Boynton
* @author Arthur van Hoff
@@ -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. For example, in a future release, synchronization may fail.
*
* @author Lee Boynton
* @author Arthur van Hoff
@@ -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. For example, in a future release, synchronization may fail.
*
* <p>Implementation note: The implementations of the "bit twiddling"
* methods (such as {@link #highestOneBit(int) highestOneBit} and
@@ -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. For example, in a future release, synchronization may fail.
*
* <p>Implementation note: The implementations of the "bit twiddling"
* methods (such as {@link #highestOneBit(long) highestOneBit} and
@@ -84,6 +84,7 @@
* 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.
* For example, in a future release, synchronization may fail.
* Use the {@code equals} or {@link #compareTo(ProcessHandle) compareTo} methods
* to compare ProcessHandles.
*
@@ -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. For example, in a future release, synchronization may fail.</p>
*
* @since 9
*/
@@ -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. For example, in a future release, synchronization may fail.
*
* @author Nakul Saraiya
* @author Joseph D. Darcy
@@ -61,8 +61,13 @@ <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.
For example, synchronization may fail.</p>

</body>
</html>
@@ -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. For example, in a future release, synchronization may fail.
* The {@code equals} method should be used for comparisons.
*
* @implSpec
* This class is immutable and thread-safe.
@@ -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. For example, in a future release, synchronization may fail.
* The {@code equals} method should be used for comparisons.
*
* @implSpec
* This class is immutable and thread-safe.
@@ -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. For example, in a future release, synchronization may fail.
* The {@code equals} method should be used for comparisons.
*
* @implSpec
* This class is immutable and thread-safe.
@@ -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. For example, in a future release, synchronization may fail.
* The {@code equals} method should be used for comparisons.
*
* @implSpec
* This class is immutable and thread-safe.
@@ -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. For example, in a future release, synchronization may fail.
* The {@code equals} method should be used for comparisons.
*
* @implSpec
* This class is immutable and thread-safe.
@@ -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. For example, in a future release, synchronization may fail.
* The {@code equals} method should be used for comparisons.
*
* @implSpec
* This class is immutable and thread-safe.
@@ -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. For example, in a future release, synchronization may fail.
* The {@code equals} method should be used for comparisons.
*
* @implSpec
* This class is immutable and thread-safe.
@@ -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. For example, in a future release, synchronization may fail.
* The {@code equals} method should be used for comparisons.
*
* @implSpec
* This class is immutable and thread-safe.
@@ -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. For example, in a future release, synchronization may fail.
* The {@code equals} method should be used for comparisons.
*
* @implSpec
* This class is immutable and thread-safe.
@@ -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. For example, in a future release, synchronization may fail.
* The {@code equals} method should be used for comparisons.
*
* @implSpec
* This class is immutable and thread-safe.
@@ -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. For example, in a future release, synchronization may fail.
* The {@code equals} method should be used for comparisons.
*
* @implSpec
* This class is immutable and thread-safe.
@@ -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. For example, in a future release, synchronization may fail.
* The {@code equals} method should be used for comparisons.
*
* @implSpec
* This abstract class has two implementations, both of which are immutable and thread-safe.
@@ -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. For example, in a future release, synchronization may fail.
* The {@code equals} method should be used for comparisons.
*
* @implSpec
* This class is immutable and thread-safe.
@@ -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. For example, in a future release, synchronization may fail.
* The {@code equals} method should be used for comparisons.
*
* @implSpec
* A {@code ZonedDateTime} holds state equivalent to three separate objects,
@@ -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. For example, in a future release, synchronization may fail.
* The {@code equals} method should be used for comparisons.
*
* @implSpec
* This class is immutable and thread-safe.
@@ -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. For example, in a future release, synchronization may fail.
* The {@code equals} method should be used for comparisons.
*
* @implSpec
* This class is immutable and thread-safe.
@@ -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. For example, in a future release, synchronization may fail.
* The {@code equals} method should be used for comparisons.
*
* @implSpec
* This class is immutable and thread-safe.
@@ -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. For example, in a future release, synchronization may fail.
* The {@code equals} method should be used for comparisons.
*
* @implSpec
* This class is immutable and thread-safe.
@@ -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. For example, in a future release, synchronization may fail.
*
* @apiNote
* This class is not public. Instances can be created using the
@@ -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. For example, in a future release,
* synchronization may fail. 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>
@@ -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. For example, in a future release,
* synchronization may fail. 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 @@ default V merge(K key, V value,
* <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. For example, in a future release,
* synchronization may fail. 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>
@@ -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. For example, in a future release, synchronization may fail.
*
* @apiNote
* {@code Optional} is primarily intended for use as a method return type where
@@ -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. For example, in a future release, synchronization may fail.
*
* @apiNote
* {@code OptionalDouble} is primarily intended for use as a method return type where
@@ -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. For example, in a future release, synchronization may fail.
*
* @apiNote
* {@code OptionalInt} is primarily intended for use as a method return type where
@@ -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. For example, in a future release, synchronization may fail.
*
* @apiNote
* {@code OptionalLong} is primarily intended for use as a method return type where
@@ -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. For example, in a future release,
* synchronization may fail. 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
@@ -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. For example, in a future release, synchronization may fail.
* The {@code equals} method should be used for comparisons.
*
* @implSpec
* This class is immutable and thread-safe.
@@ -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. For example, in a future release,
* synchronization may fail. The {@code equals} method should be used for comparisons.
* <p>
* Non-platform classes should not implement {@linkplain MemoryAddress} directly.
*

0 comments on commit 54ba37b

Please sign in to comment.