8287241: Add IdentityException to report that a value object is not v…

…alid

Reviewed-by: mchung

src/java.base/share/classes/java/lang/IdentityException.java

@@ -0,0 +1,83 @@
+/*
+ * Copyright (c) 2022, 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.
+ *
+ * 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 java.lang;
+
+
+/**
+ * Thrown when an identity object is required but a value object is supplied.
+ * <p>
+ * Identity objects are required for synchronization and locking.
+ * <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">Value-based</a>
+ * objects do not have identity and cannot be used for synchronization or locking.
+ *
+ * @since Valhalla
+ */
+public class IdentityException extends RuntimeException {
+    @java.io.Serial
+    private static final long serialVersionUID = 1L;
+
+    /**
+     * Create an {@code IdentityException} with no message.
+     */
+    public IdentityException() {
+    }
+
+    /**
+     * Create an {@code IdentityException} with the class name and default message.
+     *
+     * @param clazz the class of the object
+     */
+    public IdentityException(Class<?> clazz) {
+        super(clazz.getName() + " is not an identity class");
+    }
+
+    /**
+     * Create an {@code IdentityException} with a message.
+     *
+     * @param  message the detail message; can be {@code null}
+     */
+    public IdentityException(String message) {
+        super(message);
+    }
+
+    /**
+     * Create an {@code IdentityException} with a cause.
+     *
+     * @param  cause the cause; {@code null} is permitted, and indicates
+     *               that the cause is nonexistent or unknown.
+     */
+    public IdentityException(Throwable cause) {
+        super(cause);
+    }
+
+    /**
+     * Create an {@code IdentityException} with a message and cause.
+     *
+     * @param  message the detail message; can be {@code null}
+     * @param  cause the cause; {@code null} is permitted, and indicates
+     *               that the cause is nonexistent or unknown.
+     */
+    public IdentityException(String message, Throwable cause) {
+        super(message, cause);
+    }
+}

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

@@ -31,11 +31,17 @@
 import jdk.internal.access.SharedSecrets;
 import jdk.internal.ref.Cleaner;
 
+import java.util.Objects;
+
 /**
  * Abstract base class for reference objects.  This class defines the
  * operations common to all reference objects.  Because reference objects are
  * implemented in close cooperation with the garbage collector, this class may
  * not be subclassed directly.
+ * <p>
+ * References can only refer to identity objects.
+ * Attempts to create a reference to a {@linkplain Class#isValue() value object}
+ * results in an {@link IdentityException}.
  *
  * @author   Mark Reinhold
  * @since    1.2
@@ -498,11 +504,8 @@ protected Object clone() throws CloneNotSupportedException {
     }
 
     Reference(T referent, ReferenceQueue<? super T> queue) {
-        if (referent != null && referent.getClass().isValue()) {
-            Class<?> c = referent.getClass();
-            throw new IllegalArgumentException("cannot reference a " +
-                    (c.isPrimitiveClass() ? "primitive class " : "value class ") +
-                    c.getName());
+        if (referent != null) {
+            Objects.requireIdentity(referent);
         }
         this.referent = referent;
         this.queue = (queue == null) ? ReferenceQueue.NULL : queue;

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

@@ -189,6 +189,66 @@ public static String toIdentityString(Object o) {
         return o.getClass().getName() + "@" + Integer.toHexString(System.identityHashCode(o));
     }
 
+    /**
+     * Checks that the specified object reference is an identity object.
+     *
+     * @param obj the object reference to check for identity
+     * @param <T> the type of the reference
+     * @return {@code obj} if {@code obj} is an identity object
+     * @throws NullPointerException if {@code obj} is {@code null}
+     * @throws IdentityException if {@code obj} is not an identity object
+     * @since Valhalla
+     */
+    @ForceInline
+    public static <T> T requireIdentity(T obj) {
+        Objects.requireNonNull(obj);
+        var cl = obj.getClass();
+        if (cl.isValue())
+            throw new IdentityException(cl);
+        return obj;
+    }
+
+    /**
+     * Checks that the specified object reference is an identity object.
+     *
+     * @param obj the object reference to check for identity
+     * @param message detail message to be used in the event that an
+     *        {@code IdentityException} is thrown; may be null
+     * @param <T> the type of the reference
+     * @return {@code obj} if {@code obj} is an identity object
+     * @throws NullPointerException if {@code obj} is {@code null}
+     * @throws IdentityException if {@code obj} is not an identity object
+     * @since Valhalla
+     */
+    @ForceInline
+    public static <T> T requireIdentity(T obj, String message) {
+        Objects.requireNonNull(obj);
+        if (obj.getClass().isValue())
+            throw new IdentityException(message);
+        return obj;
+    }
+
+    /**
+     * Checks that the specified object reference is an identity object.
+     *
+     * @param obj the object reference to check for identity
+     * @param messageSupplier supplier of the detail message to be
+     *        used in the event that an {@code IdentityException} is thrown; may be null
+     * @param <T> the type of the reference
+     * @return {@code obj} if {@code obj} is an identity object
+     * @throws NullPointerException if {@code obj} is {@code null}
+     * @throws IdentityException if {@code obj} is not an identity object
+     * @since Valhalla
+     */
+    @ForceInline
+    public static <T> T requireIdentity(T obj, Supplier<String> messageSupplier) {
+        Objects.requireNonNull(obj);
+        if (obj.getClass().isValue())
+            throw new IdentityException(messageSupplier == null ?
+                    null : messageSupplier.get());
+        return obj;
+    }
+
     /**
      * Returns 0 if the arguments are identical and {@code
      * c.compare(a, b)} otherwise.

test/jdk/valhalla/valuetypes/WeakReferenceTest.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2019, 2022, 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
@@ -37,13 +37,13 @@
 @Test
 public class WeakReferenceTest {
 
-    @Test(expectedExceptions = IllegalArgumentException.class)
+    @Test(expectedExceptions = IdentityException.class)
     static void test1() {
         Point.ref p = new Point(10,20);
         WeakReference<Point.ref> r = new WeakReference<>(p);
     }
 
-    @Test(expectedExceptions = IllegalArgumentException.class)
+    @Test(expectedExceptions = IdentityException.class)
     static void test2() {
         ReferenceQueue<Object> q = new ReferenceQueue<>();
         Point.ref p = new Point(1,2);