8257845: Integrate JEP 390

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

src/java.base/share/classes/java/util/ImmutableCollections.java

@@ -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

src/java.base/share/classes/java/util/KeyValueHolder.java

@@ -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;

src/java.base/share/classes/java/util/List.java

@@ -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.

src/java.base/share/classes/java/util/Map.java

@@ -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

src/java.base/share/classes/java/util/Optional.java

@@ -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()}.

src/java.base/share/classes/java/util/OptionalDouble.java

@@ -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()}.

src/java.base/share/classes/java/util/OptionalInt.java

@@ -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()}.

src/java.base/share/classes/java/util/OptionalLong.java

@@ -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()}.

src/java.base/share/classes/java/util/Set.java

@@ -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.