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

[Chen Liang]

On Thu, 23 Oct 2025 23:35:18 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:
> 
>   Move the invocation dispatching spec to a large block in Proxy itself

I have decided to be a bit more ambitious and rephrased large chunks of specs in Proxy. In particular, I condensed and inlined information about duplicate methods, and reevaluated the specification about instance properties and invocation handler dispatching. I also added API notes for two interesting scenarios I discovered during my writeup, which may be of user caution.


interface Baz { int clone(); }
Baz baz = (Baz) Proxy.newProxyInstance(Baz.class.getClassLoader(),
                                       new Class<?>[] { Baz.class },
                                       (_, _, _) -> 42);
baz.clone();  // Returns 42, not a duplicate method with Object::clone

interface Foo extends java.util.concurrent.Callable<String> {
    String call(); // covariant override, descriptor changed to ()Ljava/lang/String;
}
Object foo = Proxy.newProxyInstance(Foo.class.getClassLoader(),
                                    new Class<?>[] { Foo.class },
                                    (_, _, _) -> { throw new Exception(); });
((Foo) foo).call();  // Throws UndeclaredThrowableException
((Callable<?>) foo).call();  // Throws Exception - allowed by the bridge method

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

PR Comment: https://git.openjdk.org/jdk/pull/27943#issuecomment-3439805675