RFR: 8371953: Document null handling in core reflection APIs [v2]

[Alan Bateman]

On Sun, 16 Nov 2025 15:45:24 GMT, Chen Liang <liach at openjdk.org> wrote:

>> A lot of core reflection APIs are from antique times, which have their own null handling behavior. Such behaviors are often not documented in the specification; we should document rejected null arguments and accepted null arguments (including array elements) explicitly.
>> 
>> In the investigation, I found `Class.isNestmateOf` (inconsistent) and `AnnotatedType`'s implementation of `AnnotatedElement` methods (required by specification) are missing null checks. I consider these unlikely to be a user dependency and added new null checks.
>
> Chen Liang has updated the pull request incrementally with three additional commits since the last revision:
> 
>  - Rephrase for parameterTypes contains null
>  - Rename tests to be more specific
>  - Split annotated type new checks to another patch

src/java.base/share/classes/java/lang/Class.java line 2152:

> 2150:      *         {@code name} and {@code parameterTypes}
> 2151:      * @throws NoSuchMethodException if a matching method is not found, such as
> 2152:      *         when {@code parameterTypes} contains {@code null},

It might be clear to say "or parameterTypes contains a null element" rather than "such as when ..."

src/java.base/share/classes/java/lang/Class.java line 2192:

> 2190:      *         including when this {@code Class} object represents
> 2191:      *         an interface, a primitive type, an array class, or void, and
> 2192:      *         when {@code parameterTypes} contains {@code null}

Should this be "an array class, void, or parameterTypes contains null" ?

src/java.base/share/classes/java/lang/reflect/AccessibleObject.java line 101:

> 99:      *         java.lang.Class}
> 100:      * @throws NullPointerException if {@code array} or any of its elements is
> 101:      *         {@code null}

This method does a defensive copy of the array when flag is "true". This was important for the (now removed) security manager execution mode where a permission check was specified when suppressing access checks (flag==true). Now we have this odd scenario where a null element will provoke an eager NPE if flag is true, but if flag is false then it may throw NPE after maybe re-enabling access checks on some elements. What would you think about cloning the array unconditionally and avoid needing to specifying the strange behavior.

src/java.base/share/classes/java/lang/reflect/Array.java line 121:

> 119:      * @return the length of the array
> 120:      * @throws NullPointerException if {@code array} is {@code null}
> 121:      * @throws    IllegalArgumentException if the object argument is not

Minor nit, you probably should align the two exception messages the same way.

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/28336#discussion_r2532089139
PR Review Comment: https://git.openjdk.org/jdk/pull/28336#discussion_r2532089731
PR Review Comment: https://git.openjdk.org/jdk/pull/28336#discussion_r2532088472
PR Review Comment: https://git.openjdk.org/jdk/pull/28336#discussion_r2532084127