8371953: Document null handling in core reflection APIs

Reviewed-by: alanb

Author: liach

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

@@ -160,6 +160,10 @@
  * other members are the classes and interfaces whose declarations are
  * enclosed within the top-level class declaration.
  *
+ * <p> Unless otherwise specified, methods in this class throw a
+ * {@link NullPointerException} when they are called with {@code null}
+ * or an array that contains {@code null} as an argument.
+ *
  * <h2><a id=hiddenClasses>Hidden Classes</a></h2>
  * A class or interface created by the invocation of
  * {@link java.lang.invoke.MethodHandles.Lookup#defineHiddenClass(byte[], boolean, MethodHandles.Lookup.ClassOption...)
@@ -530,7 +534,8 @@ private static Class<?> forName(String className, Class<?> caller)
      *                   (which implies linking). See Section {@jls
      *                   12.4} of <cite>The Java Language
      *                   Specification</cite>.
-     * @param loader     class loader from which the class must be loaded
+     * @param loader     class loader from which the class must be loaded,
+     *                   may be {@code null}
      * @return           class object representing the desired class
      *
      * @throws    LinkageError if the linkage fails
@@ -589,8 +594,6 @@ private static native Class<?> forName0(String name, boolean initialize,
      * @return {@code Class} object of the given name defined in the given module;
      *         {@code null} if not found.
      *
-     * @throws NullPointerException if the given module or name is {@code null}
-     *
      * @throws LinkageError if the linkage fails
      *
      * @jls 12.2 Loading of Classes and Interfaces
@@ -620,8 +623,6 @@ public static Class<?> forName(Module module, String name) {
      *
      * @param primitiveName the name of the primitive type to find
      *
-     * @throws NullPointerException if the argument is {@code null}
-     *
      * @jls 4.2 Primitive Types and Values
      * @jls 15.8.2 Class Literals
      * @since 22
@@ -757,7 +758,7 @@ public T newInstance()
      * this {@code Class} object represents a primitive type, this method
      * returns {@code false}.
      *
-     * @param   obj the object to check
+     * @param   obj the object to check, may be {@code null}
      * @return  true if {@code obj} is an instance of this class
      *
      * @since 1.1
@@ -787,8 +788,6 @@ public T newInstance()
      * @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
-     * @throws    NullPointerException if the specified Class parameter is
-     *            null.
      * @since     1.1
      */
     @IntrinsicCandidate
@@ -2057,7 +2056,6 @@ public Constructor<?>[] getConstructors() {
      *         {@code name}
      * @throws NoSuchFieldException if a field with the specified name is
      *         not found.
-     * @throws NullPointerException if {@code name} is {@code null}
      *
      * @since 1.1
      * @jls 8.2 Class Members
@@ -2148,13 +2146,13 @@ public Field getField(String name) throws NoSuchFieldException {
      * overriding method as it would have a more specific return type.
      *
      * @param name the name of the method
-     * @param parameterTypes the list of parameters
+     * @param parameterTypes the list of parameters, may be {@code null}
      * @return the {@code Method} object that matches the specified
      *         {@code name} and {@code parameterTypes}
-     * @throws NoSuchMethodException if a matching method is not found
+     * @throws NoSuchMethodException if a matching method is not found,
+     *         if {@code parameterTypes} contains {@code null},
      *         or if the name is {@value ConstantDescs#INIT_NAME} or
-     *         {@value ConstantDescs#CLASS_INIT_NAME}.
-     * @throws NullPointerException if {@code name} is {@code null}
+     *         {@value ConstantDescs#CLASS_INIT_NAME}
      *
      * @jls 8.2 Class Members
      * @jls 8.4 Method Declarations
@@ -2185,12 +2183,13 @@ public Method getMethod(String name, Class<?>... parameterTypes)
      * represented by this {@code Class} object whose formal parameter
      * types match those specified by {@code parameterTypes}.
      *
-     * @param parameterTypes the parameter array
+     * @param parameterTypes the parameter array, may be {@code null}
      * @return the {@code Constructor} object of the public constructor that
      *         matches the specified {@code parameterTypes}
      * @throws NoSuchMethodException if a matching constructor is not found,
-     *         including when this {@code Class} object represents
-     *         an interface, a primitive type, an array class, or void.
+     *         if this {@code Class} object represents an interface, a primitive
+     *         type, an array class, or void, or if {@code parameterTypes}
+     *         contains {@code null}
      *
      * @see #getDeclaredConstructor(Class[])
      * @since 1.1
@@ -2371,7 +2370,6 @@ public Constructor<?>[] getDeclaredConstructors() {
      *          class
      * @throws  NoSuchFieldException if a field with the specified name is
      *          not found.
-     * @throws  NullPointerException if {@code name} is {@code null}
      *
      * @since 1.1
      * @jls 8.2 Class Members
@@ -2406,11 +2404,13 @@ public Field getDeclaredField(String name) throws NoSuchFieldException {
      * method does not find the {@code clone()} method.
      *
      * @param name the name of the method
-     * @param parameterTypes the parameter array
-     * @return  the {@code Method} object for the method of this class
-     *          matching the specified name and parameters
-     * @throws  NoSuchMethodException if a matching method is not found.
-     * @throws  NullPointerException if {@code name} is {@code null}
+     * @param parameterTypes the parameter array, may be {@code null}
+     * @return the {@code Method} object for the method of this class
+     *         matching the specified name and parameters
+     * @throws NoSuchMethodException if a matching method is not found,
+     *         if {@code parameterTypes} contains {@code null},
+     *         or if the name is {@value ConstantDescs#INIT_NAME} or
+     *         {@value ConstantDescs#CLASS_INIT_NAME}
      *
      * @jls 8.2 Class Members
      * @jls 8.4 Method Declarations
@@ -2477,12 +2477,13 @@ Method findMethod(boolean publicOnly, String name, Class<?>... parameterTypes) {
      * declared in a non-static context, the formal parameter types
      * include the explicit enclosing instance as the first parameter.
      *
-     * @param parameterTypes the parameter array
+     * @param parameterTypes the parameter array, may be {@code null}
      * @return  The {@code Constructor} object for the constructor with the
      *          specified parameter list
      * @throws  NoSuchMethodException if a matching constructor is not found,
-     *          including when this {@code Class} object represents
-     *          an interface, a primitive type, an array class, or void.
+     *          if this {@code Class} object represents an interface, a
+     *          primitive type, an array class, or void, or if
+     *          {@code parameterTypes} contains {@code null}
      *
      * @see #getConstructor(Class[])
      * @since 1.1
@@ -2541,7 +2542,6 @@ public Constructor<T> getDeclaredConstructor(Class<?>... parameterTypes)
      *          resource with this name is found, or the resource is in a package
      *          that is not {@linkplain Module#isOpen(String, Module) open} to at
      *          least the caller module.
-     * @throws  NullPointerException If {@code name} is {@code null}
      *
      * @see Module#getResourceAsStream(String)
      * @since  1.1
@@ -2637,7 +2637,6 @@ public InputStream getResourceAsStream(String name) {
      *         resource is in a package that is not
      *         {@linkplain Module#isOpen(String, Module) open} to at least the caller
      *         module.
-     * @throws NullPointerException If {@code name} is {@code null}
      * @since  1.1
      */
     @CallerSensitive
@@ -3479,7 +3478,7 @@ Map<String, T> enumConstantDirectory() {
      * Casts an object to the class or interface represented
      * by this {@code Class} object.
      *
-     * @param obj the object to be cast
+     * @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
@@ -3534,7 +3533,6 @@ public <U> Class<? extends U> asSubclass(Class<U> clazz) {
      * <p>Note that any annotation returned by this method is a
      * declaration annotation.
      *
-     * @throws NullPointerException {@inheritDoc}
      * @since 1.5
      */
     @Override
@@ -3547,7 +3545,6 @@ public <A extends Annotation> A getAnnotation(Class<A> annotationClass) {
 
     /**
      * {@inheritDoc}
-     * @throws NullPointerException {@inheritDoc}
      * @since 1.5
      */
     @Override
@@ -3560,7 +3557,6 @@ public boolean isAnnotationPresent(Class<? extends Annotation> annotationClass)
      * <p>Note that any annotations returned by this method are
      * declaration annotations.
      *
-     * @throws NullPointerException {@inheritDoc}
      * @since 1.8
      */
     @Override
@@ -3590,7 +3586,6 @@ public Annotation[] getAnnotations() {
      * <p>Note that any annotation returned by this method is a
      * declaration annotation.
      *
-     * @throws NullPointerException {@inheritDoc}
      * @since 1.8
      */
     @Override
@@ -3606,7 +3601,6 @@ public <A extends Annotation> A getDeclaredAnnotation(Class<A> annotationClass)
      * <p>Note that any annotations returned by this method are
      * declaration annotations.
      *
-     * @throws NullPointerException {@inheritDoc}
      * @since 1.8
      */
     @Override
@@ -3837,6 +3831,7 @@ public Class<?> getNestHost() {
      * @since 11
      */
     public boolean isNestmateOf(Class<?> c) {
+        Objects.requireNonNull(c);
         if (this == c) {
             return true;
         }

src/java.base/share/classes/java/lang/reflect/AccessibleObject.java

@@ -97,6 +97,8 @@ public class AccessibleObject implements AnnotatedElement {
      *         objects in the array
      * @throws SecurityException if an element in the array is a constructor for {@code
      *         java.lang.Class}
+     * @throws NullPointerException if {@code array} or any of its elements is
+     *         {@code null}
      */
     @CallerSensitive
     public static void setAccessible(AccessibleObject[] array, boolean flag) {

src/java.base/share/classes/java/lang/reflect/Array.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2023, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 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
@@ -98,8 +98,8 @@ public static Object newInstance(Class<?> componentType, int length)
      * @param dimensions an array of {@code int} representing the dimensions of
      * the new array
      * @return the new array
-     * @throws    NullPointerException if the specified
-     * {@code componentType} argument is null
+     * @throws    NullPointerException if any of the specified
+     * {@code componentType} or {@code dimensions} arguments is null
      * @throws    IllegalArgumentException if the specified {@code dimensions}
      * argument is a zero-dimensional array, if componentType is {@link
      * Void#TYPE}, or if the number of dimensions of the requested array
@@ -117,8 +117,8 @@ public static Object newInstance(Class<?> componentType, int... dimensions)
      *
      * @param array the array
      * @return the length of the array
-     * @throws    IllegalArgumentException if the object argument is not
-     * an array
+     * @throws NullPointerException if {@code array} is {@code null}
+     * @throws IllegalArgumentException if {@code array} is not an array
      */
     @IntrinsicCandidate
     public static native int getLength(Object array)

src/java.base/share/classes/java/lang/reflect/ClassFileFormatVersion.java

@@ -433,6 +433,7 @@ public int major() {
      * ClassFileFormatVersion.valueOf(Runtime.Version.parse("17"))}
      *
      * @param rv runtime version to map to a class file format version
+     * @throws NullPointerException if {@code rv} is {@code null}
      * @throws IllegalArgumentException if the feature of version
      * argument is greater than the feature of the platform version.
      */

src/java.base/share/classes/java/lang/reflect/InaccessibleObjectException.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 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
@@ -47,7 +47,7 @@ public InaccessibleObjectException() {
      * message.
      *
      * @param msg
-     *        The detail message
+     *        The detail message, may be {@code null}
      */
     public InaccessibleObjectException(String msg) {
         super(msg);

src/java.base/share/classes/java/lang/reflect/InvocationTargetException.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 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
@@ -62,7 +62,7 @@ protected InvocationTargetException() {
     /**
      * Constructs a InvocationTargetException with a target exception.
      *
-     * @param target the target exception
+     * @param target the target exception, may be {@code null}
      */
     public InvocationTargetException(Throwable target) {
         super((Throwable)null);  // Disallow initCause
@@ -73,8 +73,8 @@ public InvocationTargetException(Throwable target) {
      * Constructs a InvocationTargetException with a target exception
      * and a detail message.
      *
-     * @param target the target exception
-     * @param s      the detail message
+     * @param target the target exception, may be {@code null}
+     * @param s      the detail message, may be {@code null}
      */
     public InvocationTargetException(Throwable target, String s) {
         super(s, null);  // Disallow initCause

src/java.base/share/classes/java/lang/reflect/MalformedParametersException.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2013, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2013, 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
@@ -65,7 +65,7 @@ public MalformedParametersException() {}
     /**
      * Create a {@code MalformedParametersException}.
      *
-     * @param reason The reason for the exception.
+     * @param reason The reason for the exception, may be {@code null}
      */
     public MalformedParametersException(String reason) {
         super(reason);

src/java.base/share/classes/java/lang/reflect/Proxy.java

@@ -897,7 +897,8 @@ private static Module getDynamicModule(ClassLoader loader) {
      * of interfaces but in a different order will result in two distinct
      * proxy classes.
      *
-     * @param   loader the class loader to define the proxy class
+     * @param   loader the class loader to define the proxy class, may be
+     *          {@code null} to represent the bootstrap class loader
      * @param   interfaces the list of interfaces for the proxy class
      *          to implement
      * @param   h the invocation handler to dispatch method invocations to

src/java.base/share/classes/java/lang/reflect/UndeclaredThrowableException.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 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
@@ -61,7 +61,7 @@ public class UndeclaredThrowableException extends RuntimeException {
      * specified {@code Throwable}.
      *
      * @param   undeclaredThrowable the undeclared checked exception
-     *          that was thrown
+     *          that was thrown, may be {@code null}
      */
     public UndeclaredThrowableException(Throwable undeclaredThrowable) {
         super(null, undeclaredThrowable);  // Disallow initCause
@@ -72,8 +72,8 @@ public UndeclaredThrowableException(Throwable undeclaredThrowable) {
      * specified {@code Throwable} and a detail message.
      *
      * @param   undeclaredThrowable the undeclared checked exception
-     *          that was thrown
-     * @param   s the detail message
+     *          that was thrown, may be {@code null}
+     * @param   s the detail message, may be {@code null}
      */
     public UndeclaredThrowableException(Throwable undeclaredThrowable,
                                         String s)