archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-08-28 07:14:30 +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