RFR: 8371953: Document null handling in core reflection APIs

[Alan Bateman]

On Sat, 15 Nov 2025 23:04:53 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.

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

> 2146:      *
> 2147:      * @param name the name of the method
> 2148:      * @param parameterTypes the list of parameters, may be or contain {@code null}

The method description already specifies that if parameterTypes is null then it works like an empty array, so "may be null" is okay here.

getMethod, getConstructor, ... throw NoSuchMethodException is the parameterTypes has a null element. Maybe it would be better to expand the description for `@throws NoSuchMethodException`? That would avoid suggesting in the parameter description that a null element is allowed.

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

> 3837:      */
> 3838:     public boolean isNestmateOf(Class<?> c) {
> 3839:         Objects.requireNonNull(c);

So the behavior change here is calling isNestmateOf(null) on a class object for a primitive or array class will throw NPE when it didn't throw it previously.  Technically an incompatible change but I agree it's in the weeds when it comes to impact.

test/jdk/java/lang/Class/APIContractTest.java line 35:

> 33: import static org.junit.jupiter.api.Assertions.*;
> 34: 
> 35: class APIContractTest {

We have a lot of existing tests that exercise the "API contract" so I think the naming of most of the tests is in this PR is a bit misleading - maybe start out with NullTests or something that makes it clear from the names that these are tests that fire nulls at everything. If some of these tests expand purpose in the future then they can be renamed.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/28336#discussion_r2531754070
PR Review Comment: https://git.openjdk.org/jdk/pull/28336#discussion_r2531755438
PR Review Comment: https://git.openjdk.org/jdk/pull/28336#discussion_r2531707408