Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / Java

InvocationHandler — handling dynamic proxy calls

InvocationHandler defines how a dynamic proxy's methods behave. Learn the InvocationHandler.invoke contract, its arguments, return-value and exception constraints, and handling of Object methods.

Version: Java SE 21; repository runtime, production runtime not attested

Syntax

Object invoke(Object proxy, Method method, Object[] args) throws Throwable

java.lang.reflect.InvocationHandler handles calls on a dynamic proxy created through Proxy.newProxyInstance. The proxy implements specified interfaces; it does not provide arbitrary class inheritance. A handler can supply results without a separate target object.

InvocationHandler.invoke receives proxy, the method description method, and an args array (null for a parameterless method). Primitive arguments are boxed. If the proxy method has a primitive return type, the handler must return the corresponding wrapper; returning null causes NullPointerException. For a reference return type, null is valid. In either case, a non-null result of an incompatible type causes ClassCastException. If the proxy method returns void, the handler's result is discarded.

An undeclared checked exception is wrapped in UndeclaredThrowableException. Calls to equals, hashCode, and toString also reach the handler. Do not call the intercepted method again on proxy: this risks recursion. Default methods also pass through the handler; their implementations can be invoked using InvocationHandler.invokeDefault.

The example defines behavior for Greeting and the three Object methods. It deliberately handles one interface, rather than providing general-purpose delegation. Scope: Java SE 21; the repository runtime does not attest the production runtime.

Examples

import java.lang.reflect.InvocationHandler;
import java.lang.reflect.Proxy;

public class Main {
    public interface Greeting {
        String greet(String name);
    }

    public static void main(String[] args) {
        InvocationHandler handler = (proxy, method, arguments) -> {
            if (method.getDeclaringClass() == Object.class) {
                return switch (method.getName()) {
                    case "equals" -> proxy == arguments[0];
                    case "hashCode" -> System.identityHashCode(proxy);
                    case "toString" -> "GreetingProxy";
                    default -> throw new UnsupportedOperationException(method.getName());
                };
            }
            return "Hello, " + arguments[0];
        };

        Greeting greeting = (Greeting) Proxy.newProxyInstance(
                Greeting.class.getClassLoader(),
                new Class<?>[] { Greeting.class }, handler);

        System.out.println(greeting.greet("Ada"));
        System.out.println(greeting);
    }
}

Result

Hello, Ada
GreetingProxy

The displayed code and declared result were verified in an isolated environment using the method recorded in the verification evidence for this exact version.

Sources