stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

8028816: Add value-type notice to Optional* classes

Browse Source 
Reviewed-by: mduigou, smarks
This commit is contained in:
Shinya Yoshida 2013-12-03 21:22:14 -08:00 committed by Brian Goetz
parent 170b3229bc
commit eefd90c801
5 changed files with 65 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
jdk/src/share/classes/java/lang/doc-files/ValueBased.html Normal file
View File

@ -0,0 +1,42 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html lang="en">
<head>
<title>Value-based Classes</title>
<link rel="stylesheet" type="text/css" href="../../../stylesheet.css" title="Style">
</head>
<body>
<h2 id="ValueBased">Value-based Classes</h2>
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:
<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 committment 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>
</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
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>
</body>
</html>

5
jdk/src/share/classes/java/util/Optional.java
View File

@ -40,6 +40,11 @@ import java.util.function.Supplier;
* {@link #ifPresent(java.util.function.Consumer) ifPresent()} (execute a block * {@link #ifPresent(java.util.function.Consumer) ifPresent()} (execute a block
* of code if the value is present). * of code if the 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.
*
* @since 1.8 * @since 1.8
*/ */
public final class Optional<T> { public final class Optional<T> {

7
jdk/src/share/classes/java/util/OptionalDouble.java
View File

@ -31,7 +31,7 @@ import java.util.function.Supplier;
/** /**
* A container object which may or may not contain a {@code double} value. * A container object which may or may not contain a {@code double} value.
* If a value is present, {@code isPresent()} will return {@code true} and * If a value is present, {@code isPresent()} will return {@code true} and
* {@code get()} will return the value. * {@code getAsDouble()} will return the value.
* *
* <p>Additional methods that depend on the presence or absence of a contained * <p>Additional methods that depend on the presence or absence of a contained
* value are provided, such as {@link #orElse(double) orElse()} * value are provided, such as {@link #orElse(double) orElse()}
@ -39,6 +39,11 @@ import java.util.function.Supplier;
* {@link #ifPresent(java.util.function.DoubleConsumer) ifPresent()} (execute a block * {@link #ifPresent(java.util.function.DoubleConsumer) ifPresent()} (execute a block
* of code if the value is present). * of code if the 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.
*
* @since 1.8 * @since 1.8
*/ */
public final class OptionalDouble { public final class OptionalDouble {

7
jdk/src/share/classes/java/util/OptionalInt.java
View File

@ -31,7 +31,7 @@ import java.util.function.Supplier;
/** /**
* A container object which may or may not contain a {@code int} value. * 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 * If a value is present, {@code isPresent()} will return {@code true} and
* {@code get()} will return the value. * {@code getAsInt()} will return the value.
* *
* <p>Additional methods that depend on the presence or absence of a contained * <p>Additional methods that depend on the presence or absence of a contained
* value are provided, such as {@link #orElse(int) orElse()} * value are provided, such as {@link #orElse(int) orElse()}
@ -39,6 +39,11 @@ import java.util.function.Supplier;
* {@link #ifPresent(java.util.function.IntConsumer) ifPresent()} (execute a block * {@link #ifPresent(java.util.function.IntConsumer) ifPresent()} (execute a block
* of code if the value is present). * of code if the 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.
*
* @since 1.8 * @since 1.8
*/ */
public final class OptionalInt { public final class OptionalInt {

7
jdk/src/share/classes/java/util/OptionalLong.java
View File

@ -31,7 +31,7 @@ import java.util.function.Supplier;
/** /**
* A container object which may or may not contain a {@code long} value. * 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 * If a value is present, {@code isPresent()} will return {@code true} and
* {@code get()} will return the value. * {@code getAsLong()} will return the value.
* *
* <p>Additional methods that depend on the presence or absence of a contained * <p>Additional methods that depend on the presence or absence of a contained
* value are provided, such as {@link #orElse(long) orElse()} * value are provided, such as {@link #orElse(long) orElse()}
@ -39,6 +39,11 @@ import java.util.function.Supplier;
* {@link #ifPresent(java.util.function.LongConsumer) ifPresent()} (execute a block * {@link #ifPresent(java.util.function.LongConsumer) ifPresent()} (execute a block
* of code if the value is present). * of code if the 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.
*
* @since 1.8 * @since 1.8
*/ */
public final class OptionalLong { public final class OptionalLong {