RFR: 4397513: (reflect) InvocationHandler.invoke javadoc slightly misleading for "method" parameter [v3]

[Chen Liang]

On Thu, 23 Oct 2025 23:46:00 GMT, Chen Liang <liach at openjdk.org> wrote:

>> The `method` parameter documentation for `InvocationHandler::invoke` does not indicate that it may be one of the 3 Object methods `hashCode`, `equals`, or `toString`. This doc-only improvement clarifies that, links to the Proxy section about declaring class selection, and updates the "the interface method" occurrences to be "the invoked method" to reflect the method may be from `Object`.
>
> Chen Liang has updated the pull request incrementally with one additional commit since the last revision:
> 
>   grammar

src/java.base/share/classes/java/lang/reflect/Proxy.java line 105:

> 103:  * creation, in the same order. Invoking {@link Class#getInterfaces() getInterfaces}
> 104:  * on its {@code Class} object will return an array containing the same
> 105:  * list of interfaces (in the order specified at its creation), invoking

Class.getInterfaces is already specified to be ordered, this is redundant.

src/java.base/share/classes/java/lang/reflect/Proxy.java line 131:

> 129:  * a {@code ClassCastException}):
> 130:  * <pre>
> 131:  *     {@code (Foo) proxy}

Duplicate with proxy class properties "A proxy class extends `java.lang.reflect.Proxy`"

src/java.base/share/classes/java/lang/reflect/Proxy.java line 266:

> 264:  * the public, non-final methods of {@code java.lang.Object}
> 265:  * logically precede all of the proxy interfaces for the determination of
> 266:  * which {@code Method} object to pass to the invocation handler.

These 2 paragraphs are inlined into:

> One `Method` object is shared for all duplicate methods of each
> name and parameter types pair.  It represents the method from the first
> class or interface that contains one of these duplicate methods, in the
> sequence of the `Object` class followed by the proxy interfaces in
> their specified order.

src/java.base/share/classes/java/lang/reflect/Proxy.java line 281:

> 279:  * {@code getExceptionTypes} on the {@code Method} object
> 280:  * passed to the {@code invoke} method can necessarily be thrown
> 281:  * successfully by the {@code invoke} method.

Inlined, and also added different descriptor trick notes:

> If the invoked method is a duplicate method, and the checked
> exception is allowed by the `throws` clause of those duplicate
> methods with the same method descriptor, it is thrown by the invoked
> method.  This may be more restrictive than or be unrelated to the
> declared exceptions on the passed `Method` object, which may
> represent a duplicate method with a different method descriptor.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/27943#discussion_r2457940606
PR Review Comment: https://git.openjdk.org/jdk/pull/27943#discussion_r2457944576
PR Review Comment: https://git.openjdk.org/jdk/pull/27943#discussion_r2457962833
PR Review Comment: https://git.openjdk.org/jdk/pull/27943#discussion_r2457968185