From a2196e20608a1acd12c84ecfb8522bf1666545f4 Mon Sep 17 00:00:00 2001
From: Chen Liang <liach@openjdk.org>
Date: Thu, 30 Oct 2025 16:51:36 +0000
Subject: [PATCH] 4397513: Misleading "interface method" in InvocationHandler
 specification

Reviewed-by: alanb, jpai
---
 .../java/lang/reflect/InvocationHandler.java  | 21 +++++++++----------
 1 file changed, 10 insertions(+), 11 deletions(-)

diff --git a/src/java.base/share/classes/java/lang/reflect/InvocationHandler.java b/src/java.base/share/classes/java/lang/reflect/InvocationHandler.java
index 47c6c410241..4007595d632 100644
--- a/src/java.base/share/classes/java/lang/reflect/InvocationHandler.java
+++ b/src/java.base/share/classes/java/lang/reflect/InvocationHandler.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2025, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -54,41 +54,40 @@ public interface InvocationHandler {
      * @param   proxy the proxy instance that the method was invoked on
      *
      * @param   method the {@code Method} instance corresponding to
-     * the interface method invoked on the proxy instance.  The declaring
-     * class of the {@code Method} object will be the interface that
-     * the method was declared in, which may be a superinterface of the
-     * proxy interface that the proxy class inherits the method through.
+     * the method invoked on the proxy instance; the declaring
+     * class of the {@code Method} object may be a proxy interface,
+     * one of their superinterfaces, or the {@code Object} class
      *
      * @param   args an array of objects containing the values of the
      * arguments passed in the method invocation on the proxy instance,
-     * or {@code null} if interface method takes no arguments.
+     * or {@code null} if the invoked method takes no arguments.
      * Arguments of primitive types are wrapped in instances of the
      * appropriate primitive wrapper class, such as
      * {@code java.lang.Integer} or {@code java.lang.Boolean}.
      *
      * @return  the value to return from the method invocation on the
-     * proxy instance.  If the declared return type of the interface
+     * proxy instance.  If the declared return type of the invoked
      * method is a primitive type, then the value returned by
      * this method must be an instance of the corresponding primitive
      * wrapper class; otherwise, it must be a type assignable to the
      * declared return type.  If the value returned by this method is
-     * {@code null} and the interface method's return type is
+     * {@code null} and the invoked method's return type is
      * primitive, then a {@code NullPointerException} will be
      * thrown by the method invocation on the proxy instance.  If the
      * value returned by this method is otherwise not compatible with
-     * the interface method's declared return type as described above,
+     * the invoked method's declared return type as described above,
      * a {@code ClassCastException} will be thrown by the method
      * invocation on the proxy instance.
      *
      * @throws  Throwable the exception to throw from the method
      * invocation on the proxy instance.  The exception's type must be
      * assignable either to any of the exception types declared in the
-     * {@code throws} clause of the interface method or to the
+     * {@code throws} clause of the invoked method or to the
      * unchecked exception types {@code java.lang.RuntimeException}
      * or {@code java.lang.Error}.  If a checked exception is
      * thrown by this method that is not assignable to any of the
      * exception types declared in the {@code throws} clause of
-     * the interface method, then an
+     * the invoked method, then an
      * {@link UndeclaredThrowableException} containing the
      * exception that was thrown by this method will be thrown by the
      * method invocation on the proxy instance.