Dynamic Proxies in Java

A dynamic proxy is an object that the JVM creates at run time to implement one or more interfaces you choose. The proxy has no code of its own for the interface methods. Instead, every method call on it is sent to a single method, invoke, of an object called the InvocationHandler. The handler decides what happens: call the real object, log, measure time, check permissions, open a transaction, or answer the call itself. This is how Spring adds @Transactional behavior, how Mockito creates mocks, and how the JVM implements annotations. In this lesson, you will learn how to create a dynamic proxy, what its rules and limits are, and where it is used.

How It Works

The API

The three parameters of invoke:

Example: A Logging Proxy

Let's see an example that wraps a service so every call is logged, without changing the service or its callers:

import java.lang.reflect.InvocationHandler;
import java.lang.reflect.InvocationTargetException;
import java.lang.reflect.Method;
import java.lang.reflect.Proxy;
import java.util.Arrays;
 
public class Px {
    interface MarksService {
        int total(String student);
        void add(String student, int marks);
    }
 
    static class RealMarksService implements MarksService {
        public int total(String student) {
            return student.length() * 10;
        }
 
        public void add(String student, int marks) {
            if (marks < 0) {
                throw new IllegalArgumentException("negative marks");
            }
        }
    }
 
    static class LoggingHandler implements InvocationHandler {
        private final Object target;
 
        LoggingHandler(Object target) {
            this.target = target;
        }
 
        @Override
        public Object invoke(Object proxy, Method method, Object[] args)
                throws Throwable {
            System.out.println("-> " + method.getName()
                + Arrays.toString(args));
            try {
                Object result = method.invoke(target, args);
                System.out.println("<- " + result);
                return result;
            } catch (InvocationTargetException e) {
                System.out.println("<- threw " + e.getCause());
                throw e.getCause();
            }
        }
    }
 
    public static void main(String[] args) {
        MarksService real = new RealMarksService();
        MarksService service = (MarksService) Proxy.newProxyInstance(
            MarksService.class.getClassLoader(),
            new Class<?>[] {MarksService.class},
            new LoggingHandler(real));
 
        System.out.println("total = " + service.total("Navika"));
        service.add("Srihitha", 40);
        try {
            service.add("Advitha", -1);
        } catch (IllegalArgumentException e) {
            System.out.println("caller caught: " + e.getMessage());
        }
        System.out.println(Proxy.isProxyClass(service.getClass()));
        System.out.println(service instanceof MarksService);
        System.out.println(service instanceof RealMarksService);
    }
}

-> total[Navika]
<- 60
total = 60
-> add[Srihitha, 40]
<- null
-> add[Advitha, -1]
<- threw java.lang.IllegalArgumentException: negative marks
caller caught: negative marks
true
true
false

Explanation:

1. newProxyInstance generates a new class at run time that implements MarksService, and returns an object of it. The cast to MarksService is safe because the proxy really implements that interface.
2. service.total("Navika") looks like a normal call, but it lands in LoggingHandler.invoke with the Method for total and the argument array.
3. The handler logs, calls the real object with method.invoke(target, args), logs again and returns the result. One handler covers every method of the interface, including ones added later.
4. Exceptions: method.invoke wraps the real exception in InvocationTargetException, so the handler rethrows the cause. The caller then sees the same IllegalArgumentException it would get from the real object.
5. The proxy is a MarksService but not a RealMarksService. It wraps the real object; it doesn't extend it.

Example: A Proxy with No Real Object

A handler doesn't have to forward calls anywhere. This proxy answers the interface's methods from a map, which is how some libraries turn configuration files into typed objects:

import java.lang.reflect.InvocationHandler;
import java.lang.reflect.Proxy;
import java.util.HashMap;
import java.util.Map;
 
public class Px2 {
    interface Settings {
        String theme();
        int fontSize();
 
        default String summary() {
            return theme() + " at " + fontSize() + "px";
        }
    }
 
    public static void main(String[] args) {
        Map<String, Object> values = new HashMap<>();
        values.put("theme", "dark");
        values.put("fontSize", 14);
 
        Settings settings = (Settings) Proxy.newProxyInstance(
            Settings.class.getClassLoader(),
            new Class<?>[] {Settings.class},
            (proxy, method, a) -> {
                if (method.isDefault()) {
                    return InvocationHandler.invokeDefault(proxy, method, a);
                }
                return values.get(method.getName());
            });
 
        System.out.println(settings.theme());
        System.out.println(settings.fontSize());
        System.out.println(settings.summary());
    }
}

dark
14
dark at 14px

Explanation: InvocationHandler has one abstract method, so a lambda can implement it. For theme() and fontSize(), the handler looks up the method's name in the map; the Integer 14 is unboxed to the int return type automatically. For the default method summary(), invokeDefault runs the interface's own code, which in turn calls theme() and fontSize() through the proxy.

Rules and Limits

To proxy a class that has no interface, frameworks generate a subclass at run time with a bytecode library such as Byte Buddy or CGLIB. That is why Spring can't apply @Transactional to final classes or final methods with that approach, and why a method calling another method of the same object skips the transaction logic.

Where Dynamic Proxies Are Used

Common Mistakes

Calling method.invoke(proxy, args) inside the handler. That calls the proxy again, which calls the handler again, forever, until StackOverflowError. Invoke on the real target.

Not unwrapping InvocationTargetException. Callers then receive UndeclaredThrowableException instead of the real exception.

Forgetting toString, equals and hashCode. They reach the handler too; a handler that returns null for everything breaks them.

Trying to proxy a class. Only interfaces work with java.lang.reflect.Proxy.

Interview Corner

Practice

1. Easy: Write a TimingHandler that prints how many microseconds each call took, and wrap a List<String> with it.
2. Harder: Write a handler that caches results: the first call of a method with given arguments goes to the real object; later calls with equal arguments return the stored result.

Key Takeaways