Interface InvocationHandler

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

Processes a method invocation on a proxy instance and returns the result. This method will be invoked on an invocation handler when a method is invoked on a proxy instance that it is associated with.

static Object invokeDefault(Object proxy, Method method, Object... args) throws Throwable

Invokes the specified default method on the given proxy instance with the given parameters. The given method must be a default method declared in a proxy interface of the proxy's class or inherited from its superinterface directly or indirectly.

Invoking this method behaves as if invokespecial instruction executed from the proxy class, targeting the default method in a proxy interface. This is equivalent to the invocation: X.super.m(A* a) where X is a proxy interface and the call to X.super::m(A*) is resolved to the given method.

Examples: interface A and B both declare a default implementation of method m. Interface C extends A and inherits the default method m from its superinterface A.

 interface A {
     default T m(A a) { return t1; }
 }
 interface B {
     default T m(A a) { return t2; }
 }
 interface C extends A {}
 

The following creates a proxy instance that implements A and invokes the default method A::m.

 Object proxy = Proxy.newProxyInstance(loader, new Class<?>[] { A.class },
         (o, m, params) -> {
             if (m.isDefault()) {
                 // if it's a default method, invoke it
                 return InvocationHandler.invokeDefault(o, m, params);
             }
         });
 

If a proxy instance implements both A and B, both of which provides the default implementation of method m, the invocation handler can dispatch the method invocation to A::m or B::m via the invokeDefault method. For example, the following code delegates the method invocation to B::m.

 Object proxy = Proxy.newProxyInstance(loader, new Class<?>[] { A.class, B.class },
         (o, m, params) -> {
             if (m.getName().equals("m")) {
                 // invoke B::m instead of A::m
                 Method bMethod = B.class.getMethod(m.getName(), m.getParameterTypes());
                 return InvocationHandler.invokeDefault(o, bMethod, params);
             }
         });
 

If a proxy instance implements C that inherits the default method m from its superinterface A, then the interface method invocation on "m" is dispatched to the invocation handler's invoke method with the Method object argument representing the default method A::m.

 Object proxy = Proxy.newProxyInstance(loader, new Class<?>[] { C.class },
        (o, m, params) -> {
             if (m.isDefault()) {
                 // behaves as if calling C.super.m(params)
                 return InvocationHandler.invokeDefault(o, m, params);
             }
        });
 

The invocation of method "m" on this proxy will behave as if C.super::m is called and that is resolved to invoking A::m.

Adding a default method, or changing a method from abstract to default may cause an exception if an existing code attempts to call invokeDefault to invoke a default method. For example, if C is modified to implement a default method m:

 interface C extends A {
     default T m(A a) { return t3; }
 }
 

The code above that creates proxy instance proxy with the modified C will run with no exception and it will result in calling C::m instead of A::m.

The following is another example that creates a proxy instance of C and the invocation handler calls the invokeDefault method to invoke A::m:

 C c = (C) Proxy.newProxyInstance(loader, new Class<?>[] { C.class },
         (o, m, params) -> {
             if (m.getName().equals("m")) {
                 // IllegalArgumentException thrown as {@code A::m} is not a method
                 // inherited from its proxy interface C
                 Method aMethod = A.class.getMethod(m.getName(), m.getParameterTypes());
                 return InvocationHandler.invokeDefault(o, aMethod params);
             }
         });
 c.m(...);
 

The above code runs successfully with the old version of C and A::m is invoked. When running with the new version of C, the above code will fail with IllegalArgumentException because C overrides the implementation of the same method and A::m is not accessible by a proxy instance.