--- old/src/share/classes/java/util/Optional.java 2013-12-03 14:17:02.837080173 -0800 +++ new/src/share/classes/java/util/Optional.java 2013-12-03 14:17:02.609080162 -0800 @@ -40,6 +40,11 @@ * {@link #ifPresent(java.util.function.Consumer) ifPresent()} (execute a block * of code if the value is present). * + *
This is a value-based
+ * class; use of identity-sensitive operations (including reference equality
+ * ({@code ==}), identity hash code, or synchronization) on instances of
+ * {@code Optional} may have unpredictable effects and should be avoided.
+ *
* @since 1.8
*/
public final class Optional Additional methods that depend on the presence or absence of a contained
* value are provided, such as {@link #orElse(double) orElse()}
@@ -39,6 +39,11 @@
* {@link #ifPresent(java.util.function.DoubleConsumer) ifPresent()} (execute a block
* of code if the value is present).
*
+ * This is a value-based
+ * class; use of identity-sensitive operations (including reference equality
+ * ({@code ==}), identity hash code, or synchronization) on instances of
+ * {@code OptionalDouble} may have unpredictable effects and should be avoided.
+ *
* @since 1.8
*/
public final class OptionalDouble {
--- old/src/share/classes/java/util/OptionalInt.java 2013-12-03 14:17:04.717080264 -0800
+++ new/src/share/classes/java/util/OptionalInt.java 2013-12-03 14:17:04.493080254 -0800
@@ -31,7 +31,7 @@
/**
* A container object which may or may not contain a {@code int} value.
* If a value is present, {@code isPresent()} will return {@code true} and
- * {@code get()} will return the value.
+ * {@code getAsInt()} will return the value.
*
* Additional methods that depend on the presence or absence of a contained
* value are provided, such as {@link #orElse(int) orElse()}
@@ -39,6 +39,11 @@
* {@link #ifPresent(java.util.function.IntConsumer) ifPresent()} (execute a block
* of code if the value is present).
*
+ * This is a value-based
+ * class; use of identity-sensitive operations (including reference equality
+ * ({@code ==}), identity hash code, or synchronization) on instances of
+ * {@code OptionalInt} may have unpredictable effects and should be avoided.
+ *
* @since 1.8
*/
public final class OptionalInt {
--- old/src/share/classes/java/util/OptionalLong.java 2013-12-03 14:17:05.649080310 -0800
+++ new/src/share/classes/java/util/OptionalLong.java 2013-12-03 14:17:05.429080299 -0800
@@ -31,7 +31,7 @@
/**
* A container object which may or may not contain a {@code long} value.
* If a value is present, {@code isPresent()} will return {@code true} and
- * {@code get()} will return the value.
+ * {@code getAsLong()} will return the value.
*
* Additional methods that depend on the presence or absence of a contained
* value are provided, such as {@link #orElse(long) orElse()}
@@ -39,6 +39,11 @@
* {@link #ifPresent(java.util.function.LongConsumer) ifPresent()} (execute a block
* of code if the value is present).
*
+ * This is a value-based
+ * class; use of identity-sensitive operations (including reference equality
+ * ({@code ==}), identity hash code, or synchronization) on instances of
+ * {@code OptionalLong} may have unpredictable effects and should be avoided.
+ *
* @since 1.8
*/
public final class OptionalLong {
--- /dev/null 2013-11-25 20:02:10.306908089 -0800
+++ new/src/share/classes/java/lang/doc-files/ValueBased.html 2013-12-03 14:17:06.365080344 -0800
@@ -0,0 +1,42 @@
+
+
+ A program may produce unpredictable results if it attempts to distinguish two
+ references to equal values of a value-based class, whether directly via reference
+ equality or indirectly via an appeal to synchronization, identity hashing,
+ serialization, or any other identity-sensitive mechanism. Use of such
+ identity-sensitive operations on instances of value-based classes may have
+ unpredictable effects and should be avoided.Value-based Classes
+
+Some classes, such as java.util.Optional
and
+java.time.LocalDateTime
, are value-based. Instances of a
+value-based class:
+
+
+
+equals
,
+ hashCode
, and toString
which are computed
+ solely from the instance's state and not from its identity or the state
+ of any other object or variable;==
) between instances, identity hash code of
+ instances, or synchronization on an instances's intrinsic lock;equals()
, not
+ based on reference equality (==
);x
and y
that are equal
+ according to equals()
in any computation or method
+ invocation should produce no visible change in behavior.
+