- * In addition, this class provides many methods for + * + *
In addition, this class provides many methods for * converting a {@code boolean} to a {@code String} and a * {@code String} to a {@code boolean}, as well as other * constants and methods useful when dealing with a * {@code boolean}. * + *
This is a value-based + * 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. + * * @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 c6900a5f428..c4681bc621e 100644 --- a/src/java.base/share/classes/java/lang/Byte.java +++ b/src/java.base/share/classes/java/lang/Byte.java @@ -48,6 +48,12 @@ import static java.lang.constant.ConstantDescs.DEFAULT_NAME; * byte}, as well as other constants and methods useful when dealing * with a {@code byte}. * + *
This is a value-based + * 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. + * * @author Nakul Saraiya * @author Joseph D. Darcy * @see java.lang.Number diff --git a/src/java.base/share/classes/java/lang/Character.java b/src/java.base/share/classes/java/lang/Character.java index d1b85ab0d78..ec736c68d46 100644 --- a/src/java.base/share/classes/java/lang/Character.java +++ b/src/java.base/share/classes/java/lang/Character.java @@ -122,6 +122,12 @@ import static java.lang.constant.ConstantDescs.DEFAULT_NAME; * encoding. For more information on Unicode terminology, refer to the * Unicode Glossary. * + *
This is a value-based + * 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. + * * @author Lee Boynton * @author Guy Steele * @author Akira Tanaka diff --git a/src/java.base/share/classes/java/lang/Double.java b/src/java.base/share/classes/java/lang/Double.java index 85cf88c1cf0..3a0eac5c01c 100644 --- a/src/java.base/share/classes/java/lang/Double.java +++ b/src/java.base/share/classes/java/lang/Double.java @@ -46,6 +46,12 @@ import jdk.internal.vm.annotation.IntrinsicCandidate; * constants and methods useful when dealing with a * {@code double}. * + *
This is a value-based + * 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. + * * @author Lee Boynton * @author Arthur van Hoff * @author Joseph D. Darcy diff --git a/src/java.base/share/classes/java/lang/Float.java b/src/java.base/share/classes/java/lang/Float.java index e4e815deee5..eac918824ec 100644 --- a/src/java.base/share/classes/java/lang/Float.java +++ b/src/java.base/share/classes/java/lang/Float.java @@ -45,6 +45,12 @@ import jdk.internal.vm.annotation.IntrinsicCandidate; * constants and methods useful when dealing with a * {@code float}. * + *
This is a value-based + * 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. + * * @author Lee Boynton * @author Arthur van Hoff * @author Joseph D. Darcy diff --git a/src/java.base/share/classes/java/lang/Integer.java b/src/java.base/share/classes/java/lang/Integer.java index 9694213c88b..f2a0efb089f 100644 --- a/src/java.base/share/classes/java/lang/Integer.java +++ b/src/java.base/share/classes/java/lang/Integer.java @@ -50,6 +50,12 @@ import static java.lang.String.UTF16; * {@code int}, as well as other constants and methods useful when * dealing with an {@code int}. * + *
This is a value-based + * 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. + * *
Implementation note: The implementations of the "bit twiddling" * methods (such as {@link #highestOneBit(int) highestOneBit} and * {@link #numberOfTrailingZeros(int) numberOfTrailingZeros}) are diff --git a/src/java.base/share/classes/java/lang/Long.java b/src/java.base/share/classes/java/lang/Long.java index 16afddf556a..24c3dd2c08b 100644 --- a/src/java.base/share/classes/java/lang/Long.java +++ b/src/java.base/share/classes/java/lang/Long.java @@ -50,6 +50,12 @@ import static java.lang.String.UTF16; * long}, as well as other constants and methods useful when dealing * with a {@code long}. * + *
This is a value-based + * 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. + * *
Implementation note: The implementations of the "bit twiddling" * methods (such as {@link #highestOneBit(long) highestOneBit} and * {@link #numberOfTrailingZeros(long) numberOfTrailingZeros}) are diff --git a/src/java.base/share/classes/java/lang/ProcessHandle.java b/src/java.base/share/classes/java/lang/ProcessHandle.java index cdecba1af9f..68d1ff0026d 100644 --- a/src/java.base/share/classes/java/lang/ProcessHandle.java +++ b/src/java.base/share/classes/java/lang/ProcessHandle.java @@ -81,12 +81,11 @@ import java.util.stream.Stream; *
* The {@code ProcessHandle} static factory methods return instances that are * value-based, - * immutable and thread-safe. - * Use of identity-sensitive operations (including reference equality - * ({@code ==}), identity hash code, or synchronization) on these instances of - * {@code ProcessHandle} may have unpredictable results and should be avoided. - * Use {@link #equals(Object) equals} or - * {@link #compareTo(ProcessHandle) compareTo} methods to compare ProcessHandles. + * 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 the {@code equals} or {@link #compareTo(ProcessHandle) compareTo} methods + * to compare ProcessHandles. * * @see Process * @since 9 diff --git a/src/java.base/share/classes/java/lang/Runtime.java b/src/java.base/share/classes/java/lang/Runtime.java index 38991e5c6fb..5c166ec5a1e 100644 --- a/src/java.base/share/classes/java/lang/Runtime.java +++ b/src/java.base/share/classes/java/lang/Runtime.java @@ -941,11 +941,11 @@ public class Runtime { * $VNUM(-$PRE)? * * - *
This is a value-based - * class; use of identity-sensitive operations (including reference equality - * ({@code ==}), identity hash code, or synchronization) on instances of - * {@code Version} may have unpredictable results and should be avoided. - *
+ *This is a value-based + * 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.
* * @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 42ed1e6162e..57d1dc0c0ec 100644 --- a/src/java.base/share/classes/java/lang/Short.java +++ b/src/java.base/share/classes/java/lang/Short.java @@ -47,6 +47,12 @@ import static java.lang.constant.ConstantDescs.DEFAULT_NAME; * {@code short}, as well as other constants and methods useful when * dealing with a {@code short}. * + *This is a value-based + * 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. + * * @author Nakul Saraiya * @author Joseph D. Darcy * @see java.lang.Number diff --git a/src/java.base/share/classes/java/lang/constant/ConstantDesc.java b/src/java.base/share/classes/java/lang/constant/ConstantDesc.java index 5ffb5b2aded..9d410e6774b 100644 --- a/src/java.base/share/classes/java/lang/constant/ConstantDesc.java +++ b/src/java.base/share/classes/java/lang/constant/ConstantDesc.java @@ -57,8 +57,8 @@ import java.lang.invoke.VarHandle.VarHandleDesc; *
Constants describing various common constants (such as {@link ClassDesc} * instances for platform types) can be found in {@link ConstantDescs}. * - *
Implementations of {@linkplain ConstantDesc} must be - * value-based classes. + *
Implementations of {@linkplain ConstantDesc} should be immutable + * and their behavior should not rely on object identity. * *
Non-platform classes should not implement {@linkplain ConstantDesc} directly. * Instead, they should extend {@link DynamicConstantDesc} (as {@link EnumDesc} diff --git a/src/java.base/share/classes/java/lang/constant/DynamicCallSiteDesc.java b/src/java.base/share/classes/java/lang/constant/DynamicCallSiteDesc.java index f336bc5fb4e..b57f73c0fb9 100644 --- a/src/java.base/share/classes/java/lang/constant/DynamicCallSiteDesc.java +++ b/src/java.base/share/classes/java/lang/constant/DynamicCallSiteDesc.java @@ -41,8 +41,8 @@ import static java.util.stream.Collectors.joining; * A nominal descriptor for an * {@code invokedynamic} call site. * - *
Concrete subtypes of {@linkplain DynamicCallSiteDesc} must be - * value-based. + *
Concrete subtypes of {@linkplain DynamicCallSiteDesc} should be immutable + * and their behavior should not rely on object identity. * * @since 12 */ diff --git a/src/java.base/share/classes/java/lang/constant/DynamicConstantDesc.java b/src/java.base/share/classes/java/lang/constant/DynamicConstantDesc.java index 2ff7a0ebf89..4efd3dde3c3 100644 --- a/src/java.base/share/classes/java/lang/constant/DynamicConstantDesc.java +++ b/src/java.base/share/classes/java/lang/constant/DynamicConstantDesc.java @@ -49,8 +49,8 @@ import static java.util.stream.Collectors.joining; * dynamic constant (one described in the constant pool with * {@code Constant_Dynamic_info}.) * - *
Concrete subtypes of {@linkplain DynamicConstantDesc} must be - * value-based. + *
Concrete subtypes of {@linkplain DynamicConstantDesc} should be immutable
+ * and their behavior should not rely on object identity.
*
* @param 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
+ When two instances of a value-based class are equal (according to `equals`), a program
+ 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. Use of such
- identity-sensitive operations on instances of value-based classes may have
- unpredictable effects and should be avoided.{@index "Value-based Classes"}
-Some classes, such as java.util.Optional and
-java.time.LocalDateTime, are value-based. Instances of a
-value-based class:
+Some classes, such as java.lang.Integer and
+java.time.LocalDate, are value-based.
+A value-based class has the following properties:
-
-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.
- equals, hashCode,
+ and toString compute their results solely from the values
+ of the class's instance fields (and the members of the objects they
+ reference), not from the instance's identity;x and
+ y that are equal according to equals() produces no
+ visible change in the behavior of the class's methods;equals(), they may also be
+ equal according to ==;Object or a hierarchy of
+ abstract classes that declare no instance fields or instance initializers
+ and whose constructors are empty.
Synchronization on instances of value-based classes is strongly discouraged, + because the programmer cannot guarantee exclusive ownership of the + associated monitor.