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

[Chen Liang]

On Thu, 23 Oct 2025 10:16:50 GMT, Alan Bateman <alanb 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`.
>
> src/java.base/share/classes/java/lang/reflect/InvocationHandler.java line 63:
> 
>> 61:      * declared in one of the proxy interfaces or a superinterface of them.
>> 62:      * See also the {@linkplain Proxy##duplicate-methods "Methods Duplicated in
>> 63:      * Multiple Proxy Interfaces"} section in {@code Proxy}.
> 
> The proposed wording looks okay for when a method is invoked on a proxy instance. 
> 
> InvocationHandler is not strictly tied to Proxy. I'm just wondering if the we should qualify this so that the text is in the context invoking a method on the proxy object. I'm also wondering if it should be moved to the interface description to avoid multi sentence parameter description, e.g. "When invoked on a proxy object, the method ...".  Up to you but I suspect there are wider usages of this interface.

Indeed, I think cglib uses InvocationHandler for their subclass proxies. Since you suggested to move this to the interface, I have started reviewing Proxy, and found some other intriguing properties that I don't know if it best belongs to this effort here. Will describe in another post.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/27943#discussion_r2457342276