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

@@ -1,7 +1,7 @@
  /*
-  * Copyright (c) 2009, 2023, Oracle and/or its affiliates. All rights reserved.
+  * Copyright (c) 2009, 2026, 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

@@ -23,10 +23,11 @@
   * questions.
   */
  
  package java.util;
  
+ import jdk.internal.javac.PreviewFeature;
  import jdk.internal.util.Preconditions;
  import jdk.internal.vm.annotation.ForceInline;
  
  import java.util.function.Supplier;
  

@@ -175,10 +176,99 @@
      public static String toIdentityString(Object o) {
          requireNonNull(o);
          return o.getClass().getName() + "@" + Integer.toHexString(System.identityHashCode(o));
      }
  
+    /**
+     * {@return {@code true} if the input is a non-null reference
+     * to an object with identity, and {@code false} otherwise}
+     *
+     * <p>If the object is an instance of a concrete {@linkplain Class#isValue()
+     * value class}, it does not have identity and the result will be
+     * {@code false}. All other objects, including arrays, are identity objects
+     * and the result will be {@code true}.
+     *
+     * @apiNote
+     * If the parameter is {@code null}, there is no object
+     * and hence no identity; the result is {@code false}.
+     * To test for a value object use:
+     * {@snippet type="java" :
+     *     if (obj != null && !Objects.hasIdentity(obj)) {
+     *         // obj is a non-null value object
+     *     }
+     * }
+     * @param obj an object or {@code null}
+     * @since Valhalla
+     */
+    @PreviewFeature(feature = PreviewFeature.Feature.VALUE_OBJECTS, reflective=true)
+ //    @IntrinsicCandidate
+     public static boolean hasIdentity(Object obj) {
+         return (obj == null) ? false : !obj.getClass().isValue();
+     }
+ 
+     /**
+      * 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
+      */
+     @PreviewFeature(feature = PreviewFeature.Feature.VALUE_OBJECTS)
+     @ForceInline
+     public static <T> T requireIdentity(T obj) {
+         Objects.requireNonNull(obj);
+         if (!hasIdentity(obj))
+             throw new IdentityException(obj.getClass());
+         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
+      */
+     @PreviewFeature(feature = PreviewFeature.Feature.VALUE_OBJECTS)
+     @ForceInline
+     public static <T> T requireIdentity(T obj, String message) {
+         Objects.requireNonNull(obj);
+         if (!hasIdentity(obj))
+             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
+      */
+     @PreviewFeature(feature = PreviewFeature.Feature.VALUE_OBJECTS)
+     @ForceInline
+     public static <T> T requireIdentity(T obj, Supplier<String> messageSupplier) {
+         Objects.requireNonNull(obj);
+         if (!hasIdentity(obj))
+             throw new IdentityException(messageSupplier == null ?
+                     null : messageSupplier.get());
+         return obj;
+     }
+ 
      /**
       * {@return 0 if the arguments are identical and {@code
       * c.compare(a, b)} otherwise}
       * Consequently, if both arguments are {@code null} 0
       * is returned.