diff --git a/src/java.base/share/classes/java/lang/Class.java b/src/java.base/share/classes/java/lang/Class.java index eab1993a2b4c7..ad13283f19347 100644 --- a/src/java.base/share/classes/java/lang/Class.java +++ b/src/java.base/share/classes/java/lang/Class.java @@ -734,66 +734,72 @@ 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 - * returns {@code false}. - * - * @param obj the object to check, may be {@code null} - * @return true if {@code obj} is an instance of this class - * + * 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 : + * // @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 or void, this + * method returns {@code false}. + * + * @param obj the reference to check, an object or {@code null} + * @return true the reference type represented by this {@code Class} is + * a supertype of the class of {@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 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 + * 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 +3481,28 @@ 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 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, + * 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) + * @see #isAssignableFrom(Class) * @since 1.5 */ @SuppressWarnings("unchecked")