From 3d5e795fffe94139ebaa8de89a6a85a6952de502 Mon Sep 17 00:00:00 2001 From: Chen Liang Date: Fri, 5 Dec 2025 16:09:26 -0600 Subject: [PATCH 1/4] Improve documentation of Class.isInstance --- .../share/classes/java/lang/Class.java | 133 ++++++++++-------- 1 file changed, 76 insertions(+), 57 deletions(-) diff --git a/src/java.base/share/classes/java/lang/Class.java b/src/java.base/share/classes/java/lang/Class.java index eab1993a2b4c7..a3d4ad9e03dec 100644 --- a/src/java.base/share/classes/java/lang/Class.java +++ b/src/java.base/share/classes/java/lang/Class.java @@ -734,66 +734,73 @@ public T newInstance() private transient volatile Constructor cachedConstructor; /** - * Determines if the specified {@code Object} is assignment-compatible - * with the object represented by this {@code Class}. This method is - * the dynamic equivalent of the Java language {@code instanceof} - * operator. The method returns {@code true} if the specified - * {@code Object} argument is non-null and can be cast to the - * reference type represented by this {@code Class} object without - * raising a {@code ClassCastException.} It returns {@code false} - * otherwise. - * - *

Specifically, if this {@code Class} object represents a - * declared class, this method returns {@code true} if the specified - * {@code Object} argument is an instance of the represented class (or - * of any of its subclasses); it returns {@code false} otherwise. If - * this {@code Class} object represents an array class, this method - * returns {@code true} if the specified {@code Object} argument - * can be converted to an object of the array class by an identity - * conversion or by a widening reference conversion; it returns - * {@code false} otherwise. If this {@code Class} object - * represents an interface, this method returns {@code true} if the - * class or any superclass of the specified {@code Object} argument - * implements this interface; it returns {@code false} otherwise. If - * this {@code Class} object represents a primitive type, this method + * Determines if an object reference of the type represented by this {@code + * Class} may refer to the object specified by the argument. This method is + * the dynamic equivalent of the type comparison operator of the {@code + * instanceof} Java keyword (JLS {@jls 15.20.2}). This method returns + * {@code true} if and only if this {@code Class} represents a reference + * type, the specified {@code Object} argument refers to an object instead + * of {@code null}, and that referenced object can pass the run time + * validity check of a narrowing reference conversion (JLS {@jls 5.1.6.3}) + * to the reference type represented by this {@code Class} object without + * throwing a {@code ClassCastException}. + * + *

This method behaves as if: + * {@snippet lang=java : + * // @link substring=isAssignableFrom target="#isAssignableFrom(Class)" : + * obj != null && this.isAssignableFrom(obj.getClass()) // @link substring=getClass target="Object#getClass()" + * } + * If this {@code Class} object represents a primitive type, this method * returns {@code false}. * - * @param obj the object to check, may be {@code null} - * @return true if {@code obj} is an instance of this class - * + * @param obj the reference to check, an object or {@code null} + * @return true if an object reference of the type represented by this + * {@code Class} may refer to the same object as {@code obj}; + * false otherwise + * @jls 4.3 Reference Types and Values + * @jls 5.1.6.3 Narrowing Reference Conversions at Run Time + * @see #cast(Object) + * @see #isAssignableFrom(Class) * @since 1.1 */ @IntrinsicCandidate public native boolean isInstance(Object obj); - /** - * Determines if the class or interface represented by this - * {@code Class} object is either the same as, or is a superclass or - * superinterface of, the class or interface represented by the specified - * {@code Class} parameter. It returns {@code true} if so; - * otherwise it returns {@code false}. If this {@code Class} - * object represents a primitive type, this method returns - * {@code true} if the specified {@code Class} parameter is - * exactly this {@code Class} object; otherwise it returns - * {@code false}. - * - *

Specifically, this method tests whether the type represented by the - * specified {@code Class} parameter can be converted to the type - * represented by this {@code Class} object via an identity conversion - * or via a widening reference conversion. See The Java Language - * Specification, sections {@jls 5.1.1} and {@jls 5.1.4}, - * for details. - * - * @param cls the {@code Class} object to be checked - * @return the {@code boolean} value indicating whether objects of the - * type {@code cls} can be assigned to objects of this class - * @since 1.1 + * Determines if the reference type represented by this {@code Class} object + * is the same as or a proper supertype of the reference type represented by + * the specified {@code Class} argument. + * + *

If any of the two {@code Class} objects represents a primitive type, + * this method returns {@code true} if and only if the two {@code Class} + * objects represent the same primitive type. + * + *

Otherwise, let T be the reference type represented by this object, and + * P be the reference type represented by the argument. This method + * determines whether T is a supertype of P, {@code T :> P}. Specifically: + *

+ * + * @param cls the {@code Class} object to be checked + * @return true if {@code cls} is the same as this {@code Class} object, or + * the reference type represented by {@code cls} is a subtype of the + * reference type represented by this {@code Class}; false otherwise + * @jls 4.10 Subtyping + * @see #isInstance(Object) + * @see #cast(Object) + * @since 1.1 */ @IntrinsicCandidate public native boolean isAssignableFrom(Class cls); - /** * Determines if this {@code Class} object represents an * interface type. @@ -3475,15 +3482,27 @@ Map enumConstantDirectory() { private transient volatile Map enumConstantDirectory; /** - * Casts an object to the class or interface represented - * by this {@code Class} object. - * - * @param obj the object to be cast, may be {@code null} - * @return the object after casting, or null if obj is null - * - * @throws ClassCastException if the object is not - * null and is not assignable to the type T. - * + * Casts a reference to the type represented by this {@code Class} object. + * This method is the dynamic equivalent of the cast operator with a single + * reference type (JLS {@jls 15.16}). This method performs the run time + * validity check of a narrowing reference conversion (JLS {@jls 5.1.6.3}) + * to the reference type represented by this {@code Class} object, and + * returns the incoming reference if the check does not throw a {@code + * ClassCastException}. + * + *

If this {@code Class} object represents a primitive type, this method + * completes normally if and only if the specified reference is {@code null}. + * + * @param obj the reference to be cast, an object or {@code null} + * @return the same reference in the argument + * @throws ClassCastException when the reference is not {@code null}, and + * this {@code Class} object represents either a primitive type or + * a reference type that is not a supertype of the class of the + * referenced object + * @jls 4.3 Reference Types and Values + * @jls 5.1.6.3 Narrowing Reference Conversions at Run Time + * @see #isInstance(Object) + * @see #isAssignableFrom(Class) * @since 1.5 */ @SuppressWarnings("unchecked") From 4a4f2867223cac075cb1950c83c59633f8c9e694 Mon Sep 17 00:00:00 2001 From: Chen Liang Date: Fri, 5 Dec 2025 17:23:21 -0600 Subject: [PATCH 2/4] Primitive type or void --- .../share/classes/java/lang/Class.java | 21 ++++++++++--------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/src/java.base/share/classes/java/lang/Class.java b/src/java.base/share/classes/java/lang/Class.java index a3d4ad9e03dec..9ab3c09e8b376 100644 --- a/src/java.base/share/classes/java/lang/Class.java +++ b/src/java.base/share/classes/java/lang/Class.java @@ -750,8 +750,8 @@ public T newInstance() * // @link substring=isAssignableFrom target="#isAssignableFrom(Class)" : * obj != null && this.isAssignableFrom(obj.getClass()) // @link substring=getClass target="Object#getClass()" * } - * If this {@code Class} object represents a primitive type, this method - * returns {@code false}. + * If this {@code Class} object represents a primitive type or void, this + * method returns {@code false}. * * @param obj the reference to check, an object or {@code null} * @return true if an object reference of the type represented by this @@ -771,9 +771,9 @@ public T newInstance() * is the same as or a proper supertype of the reference type represented by * the specified {@code Class} argument. * - *

If any of the two {@code Class} objects represents a primitive type, - * this method returns {@code true} if and only if the two {@code Class} - * objects represent the same primitive type. + *

If any of the two {@code Class} objects represents a primitive type or + * void, this method returns {@code true} if and only if the two {@code + * Class} objects are the same. * *

Otherwise, let T be the reference type represented by this object, and * P be the reference type represented by the argument. This method @@ -3490,15 +3490,16 @@ Map enumConstantDirectory() { * returns the incoming reference if the check does not throw a {@code * ClassCastException}. * - *

If this {@code Class} object represents a primitive type, this method - * completes normally if and only if the specified reference is {@code null}. + *

If this {@code Class} object represents a primitive type or void, this + * method completes normally if and only if the specified reference is + * {@code null}. * * @param obj the reference to be cast, an object or {@code null} * @return the same reference in the argument * @throws ClassCastException when the reference is not {@code null}, and - * this {@code Class} object represents either a primitive type or - * a reference type that is not a supertype of the class of the - * referenced object + * this {@code Class} object represents either a primitive type, + * void, or a reference type that is not a supertype of the class + * of the referenced object * @jls 4.3 Reference Types and Values * @jls 5.1.6.3 Narrowing Reference Conversions at Run Time * @see #isInstance(Object) From 5fd09962699797a30b52a1f40dd237d63e754518 Mon Sep 17 00:00:00 2001 From: Chen Liang Date: Mon, 8 Dec 2025 18:34:02 -0600 Subject: [PATCH 3/4] Non-null more straightforward than object --- src/java.base/share/classes/java/lang/Class.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/java.base/share/classes/java/lang/Class.java b/src/java.base/share/classes/java/lang/Class.java index 9ab3c09e8b376..d5670914e747b 100644 --- a/src/java.base/share/classes/java/lang/Class.java +++ b/src/java.base/share/classes/java/lang/Class.java @@ -734,7 +734,7 @@ public T newInstance() private transient volatile Constructor cachedConstructor; /** - * Determines if an object reference of the type represented by this {@code + * Determines if a non-null reference of the type represented by this {@code * Class} may refer to the object specified by the argument. This method is * the dynamic equivalent of the type comparison operator of the {@code * instanceof} Java keyword (JLS {@jls 15.20.2}). This method returns From 8dc4e31efd2ce03fc9c225b2755ac149710f2863 Mon Sep 17 00:00:00 2001 From: Chen Liang Date: Mon, 8 Dec 2025 18:47:05 -0600 Subject: [PATCH 4/4] Rewording from Kevin --- .../share/classes/java/lang/Class.java | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/src/java.base/share/classes/java/lang/Class.java b/src/java.base/share/classes/java/lang/Class.java index d5670914e747b..9807bdc4a0397 100644 --- a/src/java.base/share/classes/java/lang/Class.java +++ b/src/java.base/share/classes/java/lang/Class.java @@ -734,16 +734,16 @@ public T newInstance() private transient volatile Constructor cachedConstructor; /** - * Determines if a non-null reference of the type represented by this {@code - * Class} may refer to the object specified by the argument. This method is - * the dynamic equivalent of the type comparison operator of the {@code - * instanceof} Java keyword (JLS {@jls 15.20.2}). This method returns - * {@code true} if and only if this {@code Class} represents a reference - * type, the specified {@code Object} argument refers to an object instead - * of {@code null}, and that referenced object can pass the run time - * validity check of a narrowing reference conversion (JLS {@jls 5.1.6.3}) - * to the reference type represented by this {@code Class} object without - * throwing a {@code ClassCastException}. + * Determines if the reference type represented by this {@code Class} object + * is the same as or a proper supertype of the class of the object specified + * by the argument. This method is the dynamic equivalent of the type + * comparison operator of the {@code instanceof} Java keyword (JLS {@jls + * 15.20.2}). This method returns {@code true} if and only if this {@code + * Class} represents a reference type, the specified {@code Object} argument + * refers to an object instead of {@code null}, and that referenced object + * can pass the run time validity check of a narrowing reference conversion + * (JLS {@jls 5.1.6.3}) to the reference type represented by this {@code + * Class} object without throwing a {@code ClassCastException}. * *

This method behaves as if: * {@snippet lang=java :