archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-08-27 23:04:50 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

8257845: Integrate JEP 390

Browse source 
8254047: [JEP 390] Revise "value-based class" & apply to wrappers
8252181: [JEP 390] Define & apply annotation jdk.internal.ValueBased
8252183: [JEP 390] Add 'lint' warning for @ValueBased classes
8257027: [JEP 390] Diagnose synchronization on @ValueBased classes
8252180: [JEP 390] Deprecate wrapper class constructors for removal

Co-authored-by: Roger Riggs <rriggs@openjdk.org>
Co-authored-by: Srikanth Adayapalam <sadayapalam@openjdk.org>
Co-authored-by: Lois Foltan <lfoltan@openjdk.org>
Reviewed-by: rriggs, hseigel, mchung, darcy
This commit is contained in:
Dan Smith 2020-12-08 23:04:01 +00:00
parent ed4c4ee73b
commit 48d8650ae1
113 changed files with 695 additions and 327 deletions
Download patch file Download diff file Expand all files Collapse all files

15
src/java.base/share/classes/java/lang/Boolean.java
View file

@ -41,16 +41,23 @@ import static java.lang.constant.ConstantDescs.CD_Boolean;
* {@code boolean} in an object. An object of type
* {@code Boolean} contains a single field whose type is
* {@code boolean}.
* <p>
* In addition, this class provides many methods for
*
* <p>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}.
*
* <p>This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
* 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. For example, in a future release, synchronization may fail.
*
* @author Arthur van Hoff
* @since 1.0
*/
@jdk.internal.ValueBased
public final class Boolean implements java.io.Serializable,
Comparable<Boolean>, Constable
{
@ -98,7 +105,7 @@ public final class Boolean implements java.io.Serializable,
* Also consider using the final fields {@link #TRUE} and {@link #FALSE}
* if possible.
*/
@Deprecated(since="9")
@Deprecated(since="9", forRemoval = true)
public Boolean(boolean value) {
this.value = value;
}
@ -118,7 +125,7 @@ public final class Boolean implements java.io.Serializable,
* {@code boolean} primitive, or use {@link #valueOf(String)}
* to convert a string to a {@code Boolean} object.
*/
@Deprecated(since="9")
@Deprecated(since="9", forRemoval = true)
public Boolean(String s) {
this(parseBoolean(s));
}

11
src/java.base/share/classes/java/lang/Byte.java
View file

@ -48,11 +48,18 @@ import static java.lang.constant.ConstantDescs.DEFAULT_NAME;
* byte}, as well as other constants and methods useful when dealing
* with a {@code byte}.
*
* <p>This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
* 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. For example, in a future release, synchronization may fail.
*
* @author Nakul Saraiya
* @author Joseph D. Darcy
* @see java.lang.Number
* @since 1.1
*/
@jdk.internal.ValueBased
public final class Byte extends Number implements Comparable<Byte>, Constable {
/**
@ -337,7 +344,7 @@ public final class Byte extends Number implements Comparable<Byte>, Constable {
* {@link #valueOf(byte)} is generally a better choice, as it is
* likely to yield significantly better space and time performance.
*/
@Deprecated(since="9")
@Deprecated(since="9", forRemoval = true)
public Byte(byte value) {
this.value = value;
}
@ -360,7 +367,7 @@ public final class Byte extends Number implements Comparable<Byte>, Constable {
* {@code byte} primitive, or use {@link #valueOf(String)}
* to convert a string to a {@code Byte} object.
*/
@Deprecated(since="9")
@Deprecated(since="9", forRemoval = true)
public Byte(String s) throws NumberFormatException {
this.value = parseByte(s, 10);
}

9
src/java.base/share/classes/java/lang/Character.java
View file

@ -122,6 +122,12 @@ import static java.lang.constant.ConstantDescs.DEFAULT_NAME;
* encoding. For more information on Unicode terminology, refer to the
* <a href="http://www.unicode.org/glossary/">Unicode Glossary</a>.
*
* <p>This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
* 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. For example, in a future release, synchronization may fail.
*
* @author Lee Boynton
* @author Guy Steele
* @author Akira Tanaka
@ -129,6 +135,7 @@ import static java.lang.constant.ConstantDescs.DEFAULT_NAME;
* @author Ulf Zibis
* @since 1.0
*/
@jdk.internal.ValueBased
public final
class Character implements java.io.Serializable, Comparable<Character>, Constable {
/**
@ -8501,7 +8508,7 @@ class Character implements java.io.Serializable, Comparable<Character>, Constabl
* {@link #valueOf(char)} is generally a better choice, as it is
* likely to yield significantly better space and time performance.
*/
@Deprecated(since="9")
@Deprecated(since="9", forRemoval = true)
public Character(char value) {
this.value = value;
}

11
src/java.base/share/classes/java/lang/Double.java
View file

@ -46,11 +46,18 @@ import jdk.internal.vm.annotation.IntrinsicCandidate;
* constants and methods useful when dealing with a
* {@code double}.
*
* <p>This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
* 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. For example, in a future release, synchronization may fail.
*
* @author Lee Boynton
* @author Arthur van Hoff
* @author Joseph D. Darcy
* @since 1.0
*/
@jdk.internal.ValueBased
public final class Double extends Number
implements Comparable<Double>, Constable, ConstantDesc {
/**
@ -605,7 +612,7 @@ public final class Double extends Number
* {@link #valueOf(double)} is generally a better choice, as it is
* likely to yield significantly better space and time performance.
*/
@Deprecated(since="9")
@Deprecated(since="9", forRemoval = true)
public Double(double value) {
this.value = value;
}
@ -626,7 +633,7 @@ public final class Double extends Number
* {@code double} primitive, or use {@link #valueOf(String)}
* to convert a string to a {@code Double} object.
*/
@Deprecated(since="9")
@Deprecated(since="9", forRemoval = true)
public Double(String s) throws NumberFormatException {
value = parseDouble(s);
}

13
src/java.base/share/classes/java/lang/Float.java
View file

@ -45,11 +45,18 @@ import jdk.internal.vm.annotation.IntrinsicCandidate;
* constants and methods useful when dealing with a
* {@code float}.
*
* <p>This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
* 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. For example, in a future release, synchronization may fail.
*
* @author Lee Boynton
* @author Arthur van Hoff
* @author Joseph D. Darcy
* @since 1.0
*/
@jdk.internal.ValueBased
public final class Float extends Number
implements Comparable<Float>, Constable, ConstantDesc {
/**
@ -518,7 +525,7 @@ public final class Float extends Number
* {@link #valueOf(float)} is generally a better choice, as it is
* likely to yield significantly better space and time performance.
*/
@Deprecated(since="9")
@Deprecated(since="9", forRemoval = true)
public Float(float value) {
this.value = value;
}
@ -534,7 +541,7 @@ public final class Float extends Number
* static factory method {@link #valueOf(float)} method as follows:
* {@code Float.valueOf((float)value)}.
*/
@Deprecated(since="9")
@Deprecated(since="9", forRemoval = true)
public Float(double value) {
this.value = (float)value;
}
@ -555,7 +562,7 @@ public final class Float extends Number
* {@code float} primitive, or use {@link #valueOf(String)}
* to convert a string to a {@code Float} object.
*/
@Deprecated(since="9")
@Deprecated(since="9", forRemoval = true)
public Float(String s) throws NumberFormatException {
value = parseFloat(s);
}

11
src/java.base/share/classes/java/lang/Integer.java
View file

@ -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}.
*
* <p>This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
* 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. 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
* {@link #numberOfTrailingZeros(int) numberOfTrailingZeros}) are
@ -62,6 +68,7 @@ import static java.lang.String.UTF16;
* @author Joseph D. Darcy
* @since 1.0
*/
@jdk.internal.ValueBased
public final class Integer extends Number
implements Comparable<Integer>, Constable, ConstantDesc {
/**
@ -1085,7 +1092,7 @@ public final class Integer extends Number
* {@link #valueOf(int)} is generally a better choice, as it is
* likely to yield significantly better space and time performance.
*/
@Deprecated(since="9")
@Deprecated(since="9", forRemoval = true)
public Integer(int value) {
this.value = value;
}
@ -1107,7 +1114,7 @@ public final class Integer extends Number
* {@code int} primitive, or use {@link #valueOf(String)}
* to convert a string to an {@code Integer} object.
*/
@Deprecated(since="9")
@Deprecated(since="9", forRemoval = true)
public Integer(String s) throws NumberFormatException {
this.value = parseInt(s, 10);
}

11
src/java.base/share/classes/java/lang/Long.java
View file

@ -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}.
*
* <p>This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
* 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. 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
* {@link #numberOfTrailingZeros(long) numberOfTrailingZeros}) are
@ -62,6 +68,7 @@ import static java.lang.String.UTF16;
* @author Joseph D. Darcy
* @since 1.0
*/
@jdk.internal.ValueBased
public final class Long extends Number
implements Comparable<Long>, Constable, ConstantDesc {
/**
@ -1316,7 +1323,7 @@ public final class Long extends Number
* {@link #valueOf(long)} is generally a better choice, as it is
* likely to yield significantly better space and time performance.
*/
@Deprecated(since="9")
@Deprecated(since="9", forRemoval = true)
public Long(long value) {
this.value = value;
}
@ -1339,7 +1346,7 @@ public final class Long extends Number
* {@code long} primitive, or use {@link #valueOf(String)}
* to convert a string to a {@code Long} object.
*/
@Deprecated(since="9")
@Deprecated(since="9", forRemoval = true)
public Long(String s) throws NumberFormatException {
this.value = parseLong(s, 10);
}

13
src/java.base/share/classes/java/lang/ProcessHandle.java
View file

@ -81,16 +81,17 @@ import java.util.stream.Stream;
* <p>
* The {@code ProcessHandle} static factory methods return instances that are
* <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>,
* 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.
* For example, in a future release, synchronization may fail.
* Use the {@code equals} or {@link #compareTo(ProcessHandle) compareTo} methods
* to compare ProcessHandles.
*
* @see Process
* @since 9
*/
@jdk.internal.ValueBased
public interface ProcessHandle extends Comparable<ProcessHandle> {
/**

1
src/java.base/share/classes/java/lang/ProcessHandleImpl.java
View file

@ -48,6 +48,7 @@ import static java.security.AccessController.doPrivileged;
* @see Process
* @since 9
*/
@jdk.internal.ValueBased
final class ProcessHandleImpl implements ProcessHandle {
/**
* Default size of stack for reaper processes.

11
src/java.base/share/classes/java/lang/Runtime.java
View file

@ -941,14 +941,15 @@ public class Runtime {
* $VNUM(-$PRE)?
* </pre></blockquote>
*
* <p>This is a <a href="./doc-files/ValueBased.html">value-based</a>
* 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.
* </p>
* <p>This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
* 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. For example, in a future release, synchronization may fail.</p>
*
* @since 9
*/
@jdk.internal.ValueBased
public static final class Version
implements Comparable<Version>
{

11
src/java.base/share/classes/java/lang/Short.java
View file

@ -47,11 +47,18 @@ import static java.lang.constant.ConstantDescs.DEFAULT_NAME;
* {@code short}, as well as other constants and methods useful when
* dealing with a {@code short}.
*
* <p>This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
* 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. For example, in a future release, synchronization may fail.
*
* @author Nakul Saraiya
* @author Joseph D. Darcy
* @see java.lang.Number
* @since 1.1
*/
@jdk.internal.ValueBased
public final class Short extends Number implements Comparable<Short>, Constable {
/**
@ -342,7 +349,7 @@ public final class Short extends Number implements Comparable<Short>, Constable
* {@link #valueOf(short)} is generally a better choice, as it is
* likely to yield significantly better space and time performance.
*/
@Deprecated(since="9")
@Deprecated(since="9", forRemoval = true)
public Short(short value) {
this.value = value;
}
@ -365,7 +372,7 @@ public final class Short extends Number implements Comparable<Short>, Constable
* {@code short} primitive, or use {@link #valueOf(String)}
* to convert a string to a {@code Short} object.
*/
@Deprecated(since="9")
@Deprecated(since="9", forRemoval = true)
public Short(String s) throws NumberFormatException {
this.value = parseShort(s, 10);
}

4
src/java.base/share/classes/java/lang/constant/ConstantDesc.java
View file

@ -57,8 +57,8 @@ import java.lang.invoke.VarHandle.VarHandleDesc;
* <p>Constants describing various common constants (such as {@link ClassDesc}
* instances for platform types) can be found in {@link ConstantDescs}.
*
* <p>Implementations of {@linkplain ConstantDesc} must be
* <a href="../doc-files/ValueBased.html">value-based</a> classes.
* <p>Implementations of {@linkplain ConstantDesc} should be immutable
* and their behavior should not rely on object identity.
*
* <p>Non-platform classes should not implement {@linkplain ConstantDesc} directly.
* Instead, they should extend {@link DynamicConstantDesc} (as {@link EnumDesc}

4
src/java.base/share/classes/java/lang/constant/DynamicCallSiteDesc.java
View file

@ -41,8 +41,8 @@ import static java.util.stream.Collectors.joining;
* A <a href="package-summary.html#nominal">nominal descriptor</a> for an
* {@code invokedynamic} call site.
*
* <p>Concrete subtypes of {@linkplain DynamicCallSiteDesc} must be
* <a href="../doc-files/ValueBased.html">value-based</a>.
* <p>Concrete subtypes of {@linkplain DynamicCallSiteDesc} should be immutable
* and their behavior should not rely on object identity.
*
* @since 12
*/

4
src/java.base/share/classes/java/lang/constant/DynamicConstantDesc.java
View file

@ -49,8 +49,8 @@ import static java.util.stream.Collectors.joining;
* dynamic constant (one described in the constant pool with
* {@code Constant_Dynamic_info}.)
*
* <p>Concrete subtypes of {@linkplain DynamicConstantDesc} must be
* <a href="../doc-files/ValueBased.html">value-based</a>.
* <p>Concrete subtypes of {@linkplain DynamicConstantDesc} should be immutable
* and their behavior should not rely on object identity.
*
* @param <T> the type of the dynamic constant
*

61
src/java.base/share/classes/java/lang/doc-files/ValueBased.html
View file

@ -31,36 +31,43 @@
<body>
<h1 id="ValueBased">{@index "Value-based Classes"}</h1>
Some classes, such as <code>java.util.Optional</code> and
<code>java.time.LocalDateTime</code>, are <em>value-based</em>. Instances of a
value-based class:
Some classes, such as <code>java.lang.Integer</code> and
<code>java.time.LocalDate</code>, are <em>value-based</em>.
A value-based class has the following properties:
<ul>
<li>are final and immutable (though may contain references to mutable
objects);</li>
<li>have implementations of <code>equals</code>,
<code>hashCode</code>, and <code>toString</code> which are computed
solely from the instance's state and not from its identity or the state
of any other object or variable;</li>
<li>make no use of identity-sensitive operations such as reference
equality (<code>==</code>) between instances, identity hash code of
instances, or synchronization on an instances's intrinsic lock;</li>
<li>are considered equal solely based on <code>equals()</code>, not
based on reference equality (<code>==</code>);</li>
<li>do not have accessible constructors, but are instead instantiated
through factory methods which make no commitment as to the identity
of returned instances;</li>
<li>are <em>freely substitutable</em> when equal, meaning that interchanging
any two instances <code>x</code> and <code>y</code> that are equal
according to <code>equals()</code> in any computation or method
invocation should produce no visible change in behavior.
</li>
<li>the class declares only final instance fields (though these may contain references
to mutable objects);</li>
<li>the class's implementations of <code>equals</code>, <code>hashCode</code>,
and <code>toString</code> 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;</li>
<li>the class's methods treat instances as <em>freely substitutable</em>
when equal, meaning that interchanging any two instances <code>x</code> and
<code>y</code> that are equal according to <code>equals()</code> produces no
visible change in the behavior of the class's methods;</li>
<li>the class performs no synchronization using an instance's monitor;</li>
<li>the class does not declare (or has deprecated any) accessible constructors;</li>
<li>the class does not provide any instance creation mechanism that promises
a unique identity on each method call&mdash;in particular, any factory
method's contract must allow for the possibility that if two independently-produced
instances are equal according to <code>equals()</code>, they may also be
equal according to <code>==</code>;</li>
<li>the class is final, and extends either <code>Object</code> or a hierarchy of
abstract classes that declare no instance fields or instance initializers
and whose constructors are empty.</li>
</ul>
<p>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
<p>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.</p>
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>

2
src/java.base/share/classes/java/lang/invoke/MemberName.java
View file

@ -773,7 +773,7 @@ final class MemberName implements Member, Cloneable {
}
@Override
@SuppressWarnings("deprecation")
@SuppressWarnings({"deprecation", "removal"})
public int hashCode() {
// Avoid autoboxing getReferenceKind(), since this is used early and will force
// early initialization of Byte$ByteCache

9
src/java.base/share/classes/java/time/Duration.java
View file

@ -117,12 +117,12 @@ import java.util.regex.Pattern;
* This difference only impacts durations measured near a leap-second and should not affect
* most applications.
* See {@link Instant} for a discussion as to the meaning of the second and time-scales.
*
* <p>
* This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
* class; use of identity-sensitive operations (including reference equality
* ({@code ==}), identity hash code, or synchronization) on instances of
* {@code Duration} may have unpredictable results and should be avoided.
* 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. For example, in a future release, synchronization may fail.
* The {@code equals} method should be used for comparisons.
*
* @implSpec
@ -130,6 +130,7 @@ import java.util.regex.Pattern;
*
* @since 1.8
*/
@jdk.internal.ValueBased
public final class Duration
implements TemporalAmount, Comparable<Duration>, Serializable {

9
src/java.base/share/classes/java/time/Instant.java
View file

@ -191,12 +191,12 @@ import java.util.Objects;
* The Java time-scale is used for all date-time classes.
* This includes {@code Instant}, {@code LocalDate}, {@code LocalTime}, {@code OffsetDateTime},
* {@code ZonedDateTime} and {@code Duration}.
*
* <p>
* This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
* class; use of identity-sensitive operations (including reference equality
* ({@code ==}), identity hash code, or synchronization) on instances of
* {@code Instant} may have unpredictable results and should be avoided.
* 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. For example, in a future release, synchronization may fail.
* The {@code equals} method should be used for comparisons.
*
* @implSpec
@ -204,6 +204,7 @@ import java.util.Objects;
*
* @since 1.8
*/
@jdk.internal.ValueBased
public final class Instant
implements Temporal, TemporalAdjuster, Comparable<Instant>, Serializable {

9
src/java.base/share/classes/java/time/LocalDate.java
View file

@ -123,12 +123,12 @@ import java.util.stream.Stream;
* For most applications written today, the ISO-8601 rules are entirely suitable.
* However, any application that makes use of historical dates, and requires them
* to be accurate will find the ISO-8601 approach unsuitable.
*
* <p>
* This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
* class; use of identity-sensitive operations (including reference equality
* ({@code ==}), identity hash code, or synchronization) on instances of
* {@code LocalDate} may have unpredictable results and should be avoided.
* 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. For example, in a future release, synchronization may fail.
* The {@code equals} method should be used for comparisons.
*
* @implSpec
@ -136,6 +136,7 @@ import java.util.stream.Stream;
*
* @since 1.8
*/
@jdk.internal.ValueBased
public final class LocalDate
implements Temporal, TemporalAdjuster, ChronoLocalDate, Serializable {

9
src/java.base/share/classes/java/time/LocalDateTime.java
View file

@ -119,12 +119,12 @@ import java.util.Objects;
* For most applications written today, the ISO-8601 rules are entirely suitable.
* However, any application that makes use of historical dates, and requires them
* to be accurate will find the ISO-8601 approach unsuitable.
*
* <p>
* This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
* class; use of identity-sensitive operations (including reference equality
* ({@code ==}), identity hash code, or synchronization) on instances of
* {@code LocalDateTime} may have unpredictable results and should be avoided.
* 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. For example, in a future release, synchronization may fail.
* The {@code equals} method should be used for comparisons.
*
* @implSpec
@ -132,6 +132,7 @@ import java.util.Objects;
*
* @since 1.8
*/
@jdk.internal.ValueBased
public final class LocalDateTime
implements Temporal, TemporalAdjuster, ChronoLocalDateTime<LocalDate>, Serializable {

9
src/java.base/share/classes/java/time/LocalTime.java
View file

@ -109,12 +109,12 @@ import java.util.Objects;
* The ISO-8601 calendar system is the modern civil calendar system used today
* in most of the world. This API assumes that all calendar systems use the same
* representation, this class, for time-of-day.
*
* <p>
* This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
* class; use of identity-sensitive operations (including reference equality
* ({@code ==}), identity hash code, or synchronization) on instances of
* {@code LocalTime} may have unpredictable results and should be avoided.
* 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. For example, in a future release, synchronization may fail.
* The {@code equals} method should be used for comparisons.
*
* @implSpec
@ -122,6 +122,7 @@ import java.util.Objects;
*
* @since 1.8
*/
@jdk.internal.ValueBased
public final class LocalTime
implements Temporal, TemporalAdjuster, Comparable<LocalTime>, Serializable {

9
src/java.base/share/classes/java/time/MonthDay.java
View file

@ -111,12 +111,12 @@ import java.util.Objects;
* For most applications written today, the ISO-8601 rules are entirely suitable.
* However, any application that makes use of historical dates, and requires them
* to be accurate will find the ISO-8601 approach unsuitable.
*
* <p>
* This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
* class; use of identity-sensitive operations (including reference equality
* ({@code ==}), identity hash code, or synchronization) on instances of
* {@code MonthDay} may have unpredictable results and should be avoided.
* 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. For example, in a future release, synchronization may fail.
* The {@code equals} method should be used for comparisons.
*
* @implSpec
@ -124,6 +124,7 @@ import java.util.Objects;
*
* @since 1.8
*/
@jdk.internal.ValueBased
public final class MonthDay
implements TemporalAccessor, TemporalAdjuster, Comparable<MonthDay>, Serializable {

9
src/java.base/share/classes/java/time/OffsetDateTime.java
View file

@ -112,12 +112,12 @@ import java.util.Objects;
* It is intended that {@code ZonedDateTime} or {@code Instant} is used to model data
* in simpler applications. This class may be used when modeling date-time concepts in
* more detail, or when communicating to a database or in a network protocol.
*
* <p>
* This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
* class; use of identity-sensitive operations (including reference equality
* ({@code ==}), identity hash code, or synchronization) on instances of
* {@code OffsetDateTime} may have unpredictable results and should be avoided.
* 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. For example, in a future release, synchronization may fail.
* The {@code equals} method should be used for comparisons.
*
* @implSpec
@ -125,6 +125,7 @@ import java.util.Objects;
*
* @since 1.8
*/
@jdk.internal.ValueBased
public final class OffsetDateTime
implements Temporal, TemporalAdjuster, Comparable<OffsetDateTime>, Serializable {

9
src/java.base/share/classes/java/time/OffsetTime.java
View file

@ -102,12 +102,12 @@ import java.util.Objects;
* as well as a zone offset.
* For example, the value "13:45:30.123456789+02:00" can be stored
* in an {@code OffsetTime}.
*
* <p>
* This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
* class; use of identity-sensitive operations (including reference equality
* ({@code ==}), identity hash code, or synchronization) on instances of
* {@code OffsetTime} may have unpredictable results and should be avoided.
* 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. For example, in a future release, synchronization may fail.
* The {@code equals} method should be used for comparisons.
*
* @implSpec
@ -115,6 +115,7 @@ import java.util.Objects;
*
* @since 1.8
*/
@jdk.internal.ValueBased
public final class OffsetTime
implements Temporal, TemporalAdjuster, Comparable<OffsetTime>, Serializable {

9
src/java.base/share/classes/java/time/Period.java
View file

@ -117,12 +117,12 @@ import java.util.regex.Pattern;
* <p>
* The period is modeled as a directed amount of time, meaning that individual parts of the
* period may be negative.
*
* <p>
* This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
* class; use of identity-sensitive operations (including reference equality
* ({@code ==}), identity hash code, or synchronization) on instances of
* {@code Period} may have unpredictable results and should be avoided.
* 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. For example, in a future release, synchronization may fail.
* The {@code equals} method should be used for comparisons.
*
* @implSpec
@ -130,6 +130,7 @@ import java.util.regex.Pattern;
*
* @since 1.8
*/
@jdk.internal.ValueBased
public final class Period
implements ChronoPeriod, Serializable {

9
src/java.base/share/classes/java/time/Year.java
View file

@ -119,12 +119,12 @@ import java.util.Objects;
* For most applications written today, the ISO-8601 rules are entirely suitable.
* However, any application that makes use of historical dates, and requires them
* to be accurate will find the ISO-8601 approach unsuitable.
*
* <p>
* This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
* class; use of identity-sensitive operations (including reference equality
* ({@code ==}), identity hash code, or synchronization) on instances of
* {@code Year} may have unpredictable results and should be avoided.
* 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. For example, in a future release, synchronization may fail.
* The {@code equals} method should be used for comparisons.
*
* @implSpec
@ -132,6 +132,7 @@ import java.util.Objects;
*
* @since 1.8
*/
@jdk.internal.ValueBased
public final class Year
implements Temporal, TemporalAdjuster, Comparable<Year>, Serializable {

9
src/java.base/share/classes/java/time/YearMonth.java
View file

@ -115,12 +115,12 @@ import java.util.Objects;
* For most applications written today, the ISO-8601 rules are entirely suitable.
* However, any application that makes use of historical dates, and requires them
* to be accurate will find the ISO-8601 approach unsuitable.
*
* <p>
* This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
* class; use of identity-sensitive operations (including reference equality
* ({@code ==}), identity hash code, or synchronization) on instances of
* {@code YearMonth} may have unpredictable results and should be avoided.
* 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. For example, in a future release, synchronization may fail.
* The {@code equals} method should be used for comparisons.
*
* @implSpec
@ -128,6 +128,7 @@ import java.util.Objects;
*
* @since 1.8
*/
@jdk.internal.ValueBased
public final class YearMonth
implements Temporal, TemporalAdjuster, Comparable<YearMonth>, Serializable {

9
src/java.base/share/classes/java/time/ZoneId.java
View file

@ -160,12 +160,12 @@ import static java.util.Map.entry;
* However, any call to {@code getRules} will fail with {@code ZoneRulesException}.
* This approach is designed to allow a {@link ZonedDateTime} to be loaded and
* queried, but not modified, on a Java Runtime with incomplete time-zone information.
*
* <p>
* This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
* class; use of identity-sensitive operations (including reference equality
* ({@code ==}), identity hash code, or synchronization) on instances of
* {@code ZoneId} may have unpredictable results and should be avoided.
* 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. For example, in a future release, synchronization may fail.
* The {@code equals} method should be used for comparisons.
*
* @implSpec
@ -175,6 +175,7 @@ import static java.util.Map.entry;
*
* @since 1.8
*/
@jdk.internal.ValueBased
public abstract class ZoneId implements Serializable {
/**

9
src/java.base/share/classes/java/time/ZoneOffset.java
View file

@ -114,12 +114,12 @@ import java.util.concurrent.ConcurrentMap;
* Instances of {@code ZoneOffset} must be compared using {@link #equals}.
* Implementations may choose to cache certain common offsets, however
* applications must not rely on such caching.
*
* <p>
* This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
* class; use of identity-sensitive operations (including reference equality
* ({@code ==}), identity hash code, or synchronization) on instances of
* {@code ZoneOffset} may have unpredictable results and should be avoided.
* 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. For example, in a future release, synchronization may fail.
* The {@code equals} method should be used for comparisons.
*
* @implSpec
@ -127,6 +127,7 @@ import java.util.concurrent.ConcurrentMap;
*
* @since 1.8
*/
@jdk.internal.ValueBased
public final class ZoneOffset
extends ZoneId
implements TemporalAccessor, TemporalAdjuster, Comparable<ZoneOffset>, Serializable {

9
src/java.base/share/classes/java/time/ZonedDateTime.java
View file

@ -142,12 +142,12 @@ import java.util.Objects;
* of a {@code LocalDateTime} and a {@code ZoneId}. The {@code ZoneOffset} is
* a vital, but secondary, piece of information, used to ensure that the class
* represents an instant, especially during a daylight savings overlap.
*
* <p>
* This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
* class; use of identity-sensitive operations (including reference equality
* ({@code ==}), identity hash code, or synchronization) on instances of
* {@code ZonedDateTime} may have unpredictable results and should be avoided.
* 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. For example, in a future release, synchronization may fail.
* The {@code equals} method should be used for comparisons.
*
* @implSpec
@ -161,6 +161,7 @@ import java.util.Objects;
*
* @since 1.8
*/
@jdk.internal.ValueBased
public final class ZonedDateTime
implements Temporal, ChronoZonedDateTime<LocalDate>, Serializable {

9
src/java.base/share/classes/java/time/chrono/HijrahDate.java
View file

@ -103,12 +103,12 @@ import java.time.temporal.ValueRange;
* to create new HijrahDate instances.
* Alternatively, the {@link #withVariant} method can be used to convert
* to a new HijrahChronology.
*
* <p>
* This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
* class; use of identity-sensitive operations (including reference equality
* ({@code ==}), identity hash code, or synchronization) on instances of
* {@code HijrahDate} may have unpredictable results and should be avoided.
* 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. For example, in a future release, synchronization may fail.
* The {@code equals} method should be used for comparisons.
*
* @implSpec
@ -116,6 +116,7 @@ import java.time.temporal.ValueRange;
*
* @since 1.8
*/
@jdk.internal.ValueBased
public final class HijrahDate
extends ChronoLocalDateImpl<HijrahDate>
implements ChronoLocalDate, Serializable {

13
src/java.base/share/classes/java/time/chrono/JapaneseDate.java
View file

@ -110,12 +110,12 @@ import sun.util.calendar.LocalGregorianCalendar;
* Calling {@code japaneseDate.get(YEAR)} will return 2012.<br>
* Calling {@code japaneseDate.get(ERA)} will return 2, corresponding to
* {@code JapaneseChronology.ERA_HEISEI}.<br>
*
* <p>
* This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
* class; use of identity-sensitive operations (including reference equality
* ({@code ==}), identity hash code, or synchronization) on instances of
* {@code JapaneseDate} may have unpredictable results and should be avoided.
* 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. For example, in a future release, synchronization may fail.
* The {@code equals} method should be used for comparisons.
*
* @implSpec
@ -123,6 +123,7 @@ import sun.util.calendar.LocalGregorianCalendar;
*
* @since 1.8
*/
@jdk.internal.ValueBased
public final class JapaneseDate
extends ChronoLocalDateImpl<JapaneseDate>
implements ChronoLocalDate, Serializable {
@ -140,11 +141,11 @@ public final class JapaneseDate
/**
* The JapaneseEra of this date.
*/
private transient JapaneseEra era;
private final transient JapaneseEra era;
/**
* The Japanese imperial calendar year of this date.
*/
private transient int yearOfEra;
private final transient int yearOfEra;
/**
* The first day supported by the JapaneseChronology is Meiji 6, January 1st.

9
src/java.base/share/classes/java/time/chrono/MinguoDate.java
View file

@ -90,12 +90,12 @@ import java.util.Objects;
* This date operates using the {@linkplain MinguoChronology Minguo calendar}.
* This calendar system is primarily used in the Republic of China, often known as Taiwan.
* Dates are aligned such that {@code 0001-01-01 (Minguo)} is {@code 1912-01-01 (ISO)}.
*
* <p>
* This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
* class; use of identity-sensitive operations (including reference equality
* ({@code ==}), identity hash code, or synchronization) on instances of
* {@code MinguoDate} may have unpredictable results and should be avoided.
* 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. For example, in a future release, synchronization may fail.
* The {@code equals} method should be used for comparisons.
*
* @implSpec
@ -103,6 +103,7 @@ import java.util.Objects;
*
* @since 1.8
*/
@jdk.internal.ValueBased
public final class MinguoDate
extends ChronoLocalDateImpl<MinguoDate>
implements ChronoLocalDate, Serializable {

1
src/java.base/share/classes/java/time/chrono/ThaiBuddhistChronology.java
View file

@ -72,7 +72,6 @@ import java.time.temporal.ChronoField;
import java.time.temporal.TemporalAccessor;
import java.time.temporal.TemporalField;
import java.time.temporal.ValueRange;
import java.util.Arrays;
import java.util.HashMap;
import java.util.List;
import java.util.Locale;

9
src/java.base/share/classes/java/time/chrono/ThaiBuddhistDate.java
View file

@ -90,12 +90,12 @@ import java.util.Objects;
* This date operates using the {@linkplain ThaiBuddhistChronology Thai Buddhist calendar}.
* This calendar system is primarily used in Thailand.
* Dates are aligned such that {@code 2484-01-01 (Buddhist)} is {@code 1941-01-01 (ISO)}.
*
* <p>
* This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
* class; use of identity-sensitive operations (including reference equality
* ({@code ==}), identity hash code, or synchronization) on instances of
* {@code ThaiBuddhistDate} may have unpredictable results and should be avoided.
* 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. For example, in a future release, synchronization may fail.
* The {@code equals} method should be used for comparisons.
*
* @implSpec
@ -103,6 +103,7 @@ import java.util.Objects;
*
* @since 1.8
*/
@jdk.internal.ValueBased
public final class ThaiBuddhistDate
extends ChronoLocalDateImpl<ThaiBuddhistDate>
implements ChronoLocalDate, Serializable {

2
src/java.base/share/classes/java/time/format/TextStyle.java
View file

@ -81,7 +81,7 @@ import java.util.Calendar;
* to the word used for month in association with a day and year in a date.
*
* @implSpec
* This is immutable and thread-safe enum.
* This is an immutable and thread-safe enum.
*
* @since 1.8
*/

10
src/java.base/share/classes/java/util/ImmutableCollections.java
View file

@ -141,6 +141,7 @@ class ImmutableCollections {
static UnsupportedOperationException uoe() { return new UnsupportedOperationException(); }
@jdk.internal.ValueBased
static abstract class AbstractImmutableCollection<E> extends AbstractCollection<E> {
// all mutating methods throw UnsupportedOperationException
@Override public boolean add(E e) { throw uoe(); }
@ -247,6 +248,7 @@ class ImmutableCollections {
// ---------- List Implementations ----------
@jdk.internal.ValueBased
static abstract class AbstractImmutableList<E> extends AbstractImmutableCollection<E>
implements List<E>, RandomAccess {
@ -540,6 +542,7 @@ class ImmutableCollections {
}
}
@jdk.internal.ValueBased
static final class List12<E> extends AbstractImmutableList<E>
implements Serializable {
@ -646,6 +649,7 @@ class ImmutableCollections {
}
}
@jdk.internal.ValueBased
static final class ListN<E> extends AbstractImmutableList<E>
implements Serializable {
@ -737,6 +741,7 @@ class ImmutableCollections {
// ---------- Set Implementations ----------
@jdk.internal.ValueBased
static abstract class AbstractImmutableSet<E> extends AbstractImmutableCollection<E>
implements Set<E> {
@ -764,6 +769,7 @@ class ImmutableCollections {
public abstract int hashCode();
}
@jdk.internal.ValueBased
static final class Set12<E> extends AbstractImmutableSet<E>
implements Serializable {
@ -889,6 +895,7 @@ class ImmutableCollections {
* least one null is always present.
* @param <E> the element type
*/
@jdk.internal.ValueBased
static final class SetN<E> extends AbstractImmutableSet<E>
implements Serializable {
@ -1055,6 +1062,7 @@ class ImmutableCollections {
// ---------- Map Implementations ----------
@jdk.internal.ValueBased
abstract static class AbstractImmutableMap<K,V> extends AbstractMap<K,V> implements Serializable {
@Override public void clear() { throw uoe(); }
@Override public V compute(K key, BiFunction<? super K,? super V,? extends V> rf) { throw uoe(); }
@ -1085,6 +1093,7 @@ class ImmutableCollections {
}
}
@jdk.internal.ValueBased
static final class Map1<K,V> extends AbstractImmutableMap<K,V> {
@Stable
private final K k0;
@ -1151,6 +1160,7 @@ class ImmutableCollections {
* @param <K> the key type
* @param <V> the value type
*/
@jdk.internal.ValueBased
static final class MapN<K,V> extends AbstractImmutableMap<K,V> {
@Stable

10
src/java.base/share/classes/java/util/KeyValueHolder.java
View file

@ -31,10 +31,11 @@ import jdk.internal.vm.annotation.Stable;
* An immutable container for a key and a value, suitable for use
* in creating and populating {@code Map} instances.
*
* <p>This is a <a href="../lang/doc-files/ValueBased.html">value-based</a>
* class; use of identity-sensitive operations (including reference equality
* ({@code ==}), identity hash code, or synchronization) on instances of
* {@code KeyValueHolder} may have unpredictable results and should be avoided.
* <p>This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
* 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. For example, in a future release, synchronization may fail.
*
* @apiNote
* This class is not public. Instances can be created using the
@ -49,6 +50,7 @@ import jdk.internal.vm.annotation.Stable;
* @see Map#ofEntries Map.ofEntries()
* @since 9
*/
@jdk.internal.ValueBased
final class KeyValueHolder<K,V> implements Map.Entry<K,V> {
@Stable
final K key;

10
src/java.base/share/classes/java/util/List.java
View file

@ -107,10 +107,12 @@ import java.util.function.UnaryOperator;
* <li>The lists and their {@link #subList(int, int) subList} views implement the
* {@link RandomAccess} interface.
* <li>They are <a href="../lang/doc-files/ValueBased.html">value-based</a>.
* Callers should make no assumptions about the identity of the returned instances.
* Factories are free to create new instances or reuse existing ones. Therefore,
* identity-sensitive operations on these instances (reference equality ({@code ==}),
* identity hash code, and synchronization) are unreliable and should be avoided.
* Programmers should treat instances that are {@linkplain #equals(Object) equal}
* as interchangeable and should not use them for synchronization, or
* 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>
* page.

20
src/java.base/share/classes/java/util/Map.java
View file

@ -131,10 +131,12 @@ import java.io.Serializable;
* passed to a static factory method result in {@code IllegalArgumentException}.
* <li>The iteration order of mappings is unspecified and is subject to change.
* <li>They are <a href="../lang/doc-files/ValueBased.html">value-based</a>.
* Callers should make no assumptions about the identity of the returned instances.
* Factories are free to create new instances or reuse existing ones. Therefore,
* identity-sensitive operations on these instances (reference equality ({@code ==}),
* identity hash code, and synchronization) are unreliable and should be avoided.
* Programmers should treat instances that are {@linkplain #equals(Object) equal}
* as interchangeable and should not use them for synchronization, or
* 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>
* page.
@ -1636,10 +1638,12 @@ public interface Map<K, V> {
* on a returned {@code Entry} result in {@code UnsupportedOperationException}.
* <li>They are not serializable.
* <li>They are <a href="../lang/doc-files/ValueBased.html">value-based</a>.
* Callers should make no assumptions about the identity of the returned instances.
* This method is free to create new instances or reuse existing ones. Therefore,
* identity-sensitive operations on these instances (reference equality ({@code ==}),
* identity hash code, and synchronization) are unreliable and should be avoided.
* Programmers should treat instances that are {@linkplain #equals(Object) equal}
* as interchangeable and should not use them for synchronization, or
* 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>
*
* @apiNote

10
src/java.base/share/classes/java/util/Optional.java
View file

@ -42,10 +42,11 @@ import java.util.stream.Stream;
* {@link #ifPresent(Consumer) ifPresent()} (performs an
* action if a value is present).
*
* <p>This is a <a href="../lang/doc-files/ValueBased.html">value-based</a>
* class; use of identity-sensitive operations (including reference equality
* ({@code ==}), identity hash code, or synchronization) on instances of
* {@code Optional} may have unpredictable results and should be avoided.
* <p>This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
* 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. For example, in a future release, synchronization may fail.
*
* @apiNote
* {@code Optional} is primarily intended for use as a method return type where
@ -57,6 +58,7 @@ import java.util.stream.Stream;
* @param <T> the type of value
* @since 1.8
*/
@jdk.internal.ValueBased
public final class Optional<T> {
/**
* Common instance for {@code empty()}.

10
src/java.base/share/classes/java/util/OptionalDouble.java
View file

@ -41,10 +41,11 @@ import java.util.stream.DoubleStream;
* {@link #ifPresent(DoubleConsumer) ifPresent()} (performs
* an action if a value is present).
*
* <p>This is a <a href="../lang/doc-files/ValueBased.html">value-based</a>
* class; use of identity-sensitive operations (including reference equality
* ({@code ==}), identity hash code, or synchronization) on instances of
* {@code OptionalDouble} may have unpredictable results and should be avoided.
* <p>This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
* 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. For example, in a future release, synchronization may fail.
*
* @apiNote
* {@code OptionalDouble} is primarily intended for use as a method return type where
@ -54,6 +55,7 @@ import java.util.stream.DoubleStream;
*
* @since 1.8
*/
@jdk.internal.ValueBased
public final class OptionalDouble {
/**
* Common instance for {@code empty()}.

10
src/java.base/share/classes/java/util/OptionalInt.java
View file

@ -41,10 +41,11 @@ import java.util.stream.IntStream;
* {@link #ifPresent(IntConsumer) ifPresent()} (performs an
* action if a value is present).
*
* <p>This is a <a href="../lang/doc-files/ValueBased.html">value-based</a>
* class; use of identity-sensitive operations (including reference equality
* ({@code ==}), identity hash code, or synchronization) on instances of
* {@code OptionalInt} may have unpredictable results and should be avoided.
* <p>This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
* 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. For example, in a future release, synchronization may fail.
*
* @apiNote
* {@code OptionalInt} is primarily intended for use as a method return type where
@ -54,6 +55,7 @@ import java.util.stream.IntStream;
*
* @since 1.8
*/
@jdk.internal.ValueBased
public final class OptionalInt {
/**
* Common instance for {@code empty()}.

10
src/java.base/share/classes/java/util/OptionalLong.java
View file

@ -41,10 +41,11 @@ import java.util.stream.LongStream;
* {@link #ifPresent(LongConsumer) ifPresent()} (performs an
* action if a value is present).
*
* <p>This is a <a href="../lang/doc-files/ValueBased.html">value-based</a>
* class; use of identity-sensitive operations (including reference equality
* ({@code ==}), identity hash code, or synchronization) on instances of
* {@code OptionalLong} may have unpredictable results and should be avoided.
* <p>This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
* 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. For example, in a future release, synchronization may fail.
*
* @apiNote
* {@code OptionalLong} is primarily intended for use as a method return type where
@ -54,6 +55,7 @@ import java.util.stream.LongStream;
*
* @since 1.8
*/
@jdk.internal.ValueBased
public final class OptionalLong {
/**
* Common instance for {@code empty()}.

10
src/java.base/share/classes/java/util/Set.java
View file

@ -82,10 +82,12 @@ package java.util;
* passed to a static factory method result in {@code IllegalArgumentException}.
* <li>The iteration order of set elements is unspecified and is subject to change.
* <li>They are <a href="../lang/doc-files/ValueBased.html">value-based</a>.
* Callers should make no assumptions about the identity of the returned instances.
* Factories are free to create new instances or reuse existing ones. Therefore,
* identity-sensitive operations on these instances (reference equality ({@code ==}),
* identity hash code, and synchronization) are unreliable and should be avoided.
* Programmers should treat instances that are {@linkplain #equals(Object) equal}
* as interchangeable and should not use them for synchronization, or
* 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>
* page.