8354556: Expand value-based class warnings to java.lang.ref API

Co-authored-by: Archie Cobbs <acobbs@openjdk.org>
Reviewed-by: jlahoda

Author: Vicente Romero

make/langtools/src/classes/build/tools/symbolgenerator/CreateSymbols.java

@@ -304,13 +304,18 @@ public void createSymbols(String ctDescriptionFileExtra, String ctDescriptionFil
             "Ljdk/internal/ValueBased;";
     private static final String VALUE_BASED_ANNOTATION_INTERNAL =
             "Ljdk/internal/ValueBased+Annotation;";
+    private static final String REQUIRES_IDENTITY_ANNOTATION =
+            "Ljdk/internal/RequiresIdentity;";
+    private static final String REQUIRES_IDENTITY_ANNOTATION_INTERNAL =
+            "Ljdk/internal/RequiresIdentity+Annotation;";
     public static final Set<String> HARDCODED_ANNOTATIONS = new HashSet<>(
             List.of("Ljdk/Profile+Annotation;",
                     "Lsun/Proprietary+Annotation;",
                     PREVIEW_FEATURE_ANNOTATION_OLD,
                     PREVIEW_FEATURE_ANNOTATION_NEW,
                     VALUE_BASED_ANNOTATION,
-                    RESTRICTED_ANNOTATION));
+                    RESTRICTED_ANNOTATION,
+                    REQUIRES_IDENTITY_ANNOTATION));
 
     private void stripNonExistentAnnotations(LoadDescriptions data) {
         Set<String> allClasses = data.classes.name2Class.keySet();
@@ -1021,6 +1026,12 @@ private Annotation createAnnotation(AnnotationDescription desc) {
             annotationType = VALUE_BASED_ANNOTATION_INTERNAL;
         }
 
+        if (REQUIRES_IDENTITY_ANNOTATION.equals(annotationType)) {
+            //the non-public RequiresIdentity annotation will not be available in ct.sym,
+            //replace with purely synthetic javac-internal annotation:
+            annotationType = REQUIRES_IDENTITY_ANNOTATION_INTERNAL;
+        }
+
         if (RESTRICTED_ANNOTATION.equals(annotationType)) {
             //the non-public Restricted annotation will not be available in ct.sym,
             //replace with purely synthetic javac-internal annotation:
@@ -2202,6 +2213,7 @@ private boolean readAttribute(FeatureDescription feature, Attribute<?> attr) {
                 chd.permittedSubclasses = a.permittedSubclasses().stream().map(ClassEntry::asInternalName).collect(Collectors.toList());
             }
             case ModuleMainClassAttribute a -> ((ModuleHeaderDescription) feature).moduleMainClass = a.mainClass().asInternalName();
+            case RuntimeVisibleTypeAnnotationsAttribute a -> {/* do nothing for now */}
             default -> throw new IllegalArgumentException("Unhandled attribute: " + attr.attributeName()); // Do nothing
         }
 

src/java.base/share/classes/java/lang/ref/Cleaner.java

@@ -219,7 +219,7 @@ public static Cleaner create(ThreadFactory threadFactory) {
      * @param action a {@code Runnable} to invoke when the object becomes phantom reachable
      * @return a {@code Cleanable} instance
      */
-    public Cleanable register(Object obj, Runnable action) {
+    public Cleanable register(@jdk.internal.RequiresIdentity Object obj, Runnable action) {
         Objects.requireNonNull(obj, "obj");
         Objects.requireNonNull(action, "action");
         return new CleanerImpl.PhantomCleanableRef(obj, this, action);

src/java.base/share/classes/java/lang/ref/PhantomReference.java

@@ -51,7 +51,7 @@
  * @since    1.2
  */
 
-public non-sealed class PhantomReference<T> extends Reference<T> {
+public non-sealed class PhantomReference<@jdk.internal.RequiresIdentity T> extends Reference<T> {
 
     /**
      * Returns this reference object's referent.  Because the referent of a
@@ -101,7 +101,7 @@ void clearImpl() {
      * @param q the queue with which the reference is to be registered,
      *          or {@code null} if registration is not required
      */
-    public PhantomReference(T referent, ReferenceQueue<? super T> q) {
+    public PhantomReference(@jdk.internal.RequiresIdentity T referent, ReferenceQueue<? super T> q) {
         super(referent, q);
     }
 

src/java.base/share/classes/java/lang/ref/Reference.java

@@ -44,7 +44,7 @@
  * @sealedGraph
  */
 
-public abstract sealed class Reference<T>
+public abstract sealed class Reference<@jdk.internal.RequiresIdentity T>
     permits PhantomReference, SoftReference, WeakReference, FinalReference {
 
     /* The state of a Reference object is characterized by two attributes.  It

src/java.base/share/classes/java/lang/ref/ReferenceQueue.java

@@ -46,7 +46,7 @@
  * @since    1.2
  */
 
-public class ReferenceQueue<T> {
+public class ReferenceQueue<@jdk.internal.RequiresIdentity T> {
     private static class Null extends ReferenceQueue<Object> {
         @Override
         boolean enqueue(Reference<?> r) {

src/java.base/share/classes/java/lang/ref/SoftReference.java

@@ -62,7 +62,7 @@
  * @since    1.2
  */
 
-public non-sealed class SoftReference<T> extends Reference<T> {
+public non-sealed class SoftReference<@jdk.internal.RequiresIdentity T> extends Reference<T> {
 
     /**
      * Timestamp clock, updated by the garbage collector
@@ -82,7 +82,7 @@ public non-sealed class SoftReference<T> extends Reference<T> {
      *
      * @param referent object the new soft reference will refer to
      */
-    public SoftReference(T referent) {
+    public SoftReference(@jdk.internal.RequiresIdentity T referent) {
         super(referent);
         this.timestamp = clock;
     }
@@ -96,7 +96,7 @@ public SoftReference(T referent) {
      *          or {@code null} if registration is not required
      *
      */
-    public SoftReference(T referent, ReferenceQueue<? super T> q) {
+    public SoftReference(@jdk.internal.RequiresIdentity T referent, ReferenceQueue<? super T> q) {
         super(referent, q);
         this.timestamp = clock;
     }

src/java.base/share/classes/java/lang/ref/WeakReference.java

@@ -46,15 +46,15 @@
  * @since    1.2
  */
 
-public non-sealed class WeakReference<T> extends Reference<T> {
+public non-sealed class WeakReference<@jdk.internal.RequiresIdentity T> extends Reference<T> {
 
     /**
      * Creates a new weak reference that refers to the given object.  The new
      * reference is not registered with any queue.
      *
      * @param referent object the new weak reference will refer to
      */
-    public WeakReference(T referent) {
+    public WeakReference(@jdk.internal.RequiresIdentity T referent) {
         super(referent);
     }
 
@@ -66,7 +66,7 @@ public WeakReference(T referent) {
      * @param q the queue with which the reference is to be registered,
      *          or {@code null} if registration is not required
      */
-    public WeakReference(T referent, ReferenceQueue<? super T> q) {
+    public WeakReference(@jdk.internal.RequiresIdentity T referent, ReferenceQueue<? super T> q) {
         super(referent, q);
     }
 

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

@@ -132,7 +132,7 @@
  * @see         java.util.HashMap
  * @see         java.lang.ref.WeakReference
  */
-public class WeakHashMap<K,V>
+public class WeakHashMap<@jdk.internal.RequiresIdentity K,V>
     extends AbstractMap<K,V>
     implements Map<K,V> {
 
@@ -457,7 +457,7 @@ Entry<K,V> getEntry(Object key) {
      *         (A {@code null} return can also indicate that the map
      *         previously associated {@code null} with {@code key}.)
      */
-    public V put(K key, V value) {
+    public V put(@jdk.internal.RequiresIdentity K key, V value) {
         Object k = maskNull(key);
         int h = hash(k);
         Entry<K,V>[] tab = getTable();

src/java.base/share/classes/jdk/internal/RequiresIdentity.java

@@ -0,0 +1,51 @@
+/*
+ * Copyright (c) 2025, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+package jdk.internal;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import static java.lang.annotation.ElementType.PARAMETER;
+import static java.lang.annotation.ElementType.TYPE_PARAMETER;
+
+/**
+ * Indicates that the annotated parameter or type parameter is not expected to be a
+ * Value Based class.
+ * Using a parameter or type parameter of a <a href="../lang/doc-files/ValueBased.html">value-based classes</a>
+ * should produce warnings about behavior that is inconsistent with identity based semantics.
+ *
+ * Note this internal annotation is handled specially by the javac compiler.
+ * To work properly with {@code --release older-release}, it requires special
+ * handling in {@code make/langtools/src/classes/build/tools/symbolgenerator/CreateSymbols.java}
+ * and {@code src/jdk.compiler/share/classes/com/sun/tools/javac/jvm/ClassReader.java}.
+ *
+ * @since 25
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(value={PARAMETER, TYPE_PARAMETER})
+public @interface RequiresIdentity {
+}

src/java.base/share/classes/jdk/internal/ValueBased.java

@@ -46,4 +46,3 @@
 @Target(value={TYPE})
 public @interface ValueBased {
 }
-