Interface InvocationHandler
- All Known Implementing Classes:
CompositeDataInvocationHandler
,EventHandler
,MBeanServerInvocationHandler
,RemoteObjectInvocationHandler
InvocationHandler
is the interface implemented by
the invocation handler of a proxy instance.
Each proxy instance has an associated invocation handler.
When a method is invoked on a proxy instance, the method
invocation is encoded and dispatched to the invoke
method of its invocation handler.
- Since:
- 1.3
- See Also:
-
Method Summary
Modifier and TypeMethodDescriptionProcesses a method invocation on a proxy instance and returns the result.static Object
invokeDefault
(Object proxy, Method method, Object... args) Invokes the specified default method on the givenproxy
instance with the given parameters.
-
Method Details
-
invoke
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.- Parameters:
proxy
- the proxy instance that the method was invoked onmethod
- theMethod
instance corresponding to the interface method invoked on the proxy instance. The declaring class of theMethod
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.args
- an array of objects containing the values of the arguments passed in the method invocation on the proxy instance, ornull
if interface method takes no arguments. Arguments of primitive types are wrapped in instances of the appropriate primitive wrapper class, such asjava.lang.Integer
orjava.lang.Boolean
.- Returns:
- the value to return from the method invocation on the
proxy instance. If the declared return type of the interface
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
null
and the interface method's return type is primitive, then aNullPointerException
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, aClassCastException
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 thethrows
clause of the interface method or to the unchecked exception typesjava.lang.RuntimeException
orjava.lang.Error
. If a checked exception is thrown by this method that is not assignable to any of the exception types declared in thethrows
clause of the interface method, then anUndeclaredThrowableException
containing the exception that was thrown by this method will be thrown by the method invocation on the proxy instance.- See Also:
-
invokeDefault
Invokes the specified default method on the givenproxy
instance with the given parameters. The givenmethod
must be a default method declared in a proxy interface of theproxy
'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)
whereX
is a proxy interface and the call toX.super::m(A*)
is resolved to the givenmethod
.Examples: interface
A
andB
both declare a default implementation of methodm
. InterfaceC
extendsA
and inherits the default methodm
from its superinterfaceA
.
The following creates a proxy instance that implementsinterface A { default T m(A a) { return t1; } } interface B { default T m(A a) { return t2; } } interface C extends A {}
A
and invokes the default methodA::m
.
If a proxy instance implements bothObject 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); } });
A
andB
, both of which provides the default implementation of methodm
, the invocation handler can dispatch the method invocation toA::m
orB::m
via theinvokeDefault
method. For example, the following code delegates the method invocation toB::m
.
If a proxy instance implementsObject 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); } });
C
that inherits the default methodm
from its superinterfaceA
, then the interface method invocation on"m"
is dispatched to the invocation handler'sinvoke
method with theMethod
object argument representing the default methodA::m
.
The invocation of methodObject 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); } });
"m"
on thisproxy
will behave as ifC.super::m
is called and that is resolved to invokingA::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, ifC
is modified to implement a default methodm
:
The code above that creates proxy instanceinterface C extends A { default T m(A a) { return t3; } }
proxy
with the modifiedC
will run with no exception and it will result in callingC::m
instead ofA::m
.The following is another example that creates a proxy instance of
C
and the invocation handler calls theinvokeDefault
method to invokeA::m
:
The above code runs successfully with the old version ofC 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(...);
C
andA::m
is invoked. When running with the new version ofC
, the above code will fail withIllegalArgumentException
becauseC
overrides the implementation of the same method andA::m
is not accessible by a proxy instance.- API Note:
- The
proxy
parameter is of typeObject
rather thanProxy
to make it easy forInvocationHandler::invoke
implementation to call directly without the need of casting. - Parameters:
proxy
- theProxy
instance on which the default method to be invokedmethod
- theMethod
instance corresponding to a default method declared in a proxy interface of the proxy class or inherited from its superinterface directly or indirectlyargs
- the parameters used for the method invocation; can benull
if the number of formal parameters required by the method is zero.- Returns:
- the value returned from the method invocation
- Throws:
IllegalArgumentException
- if any of the following conditions istrue
:proxy
is not a proxy instance; or- the given
method
is not a default method declared in a proxy interface of the proxy class and not inherited from any of its superinterfaces; or - the given
method
is overridden directly or indirectly by the proxy interfaces and the method reference to the named method never resolves to the givenmethod
; or - the length of the given
args
array does not match the number of parameters of the method to be invoked; or - any of the
args
elements fails the unboxing conversion if the corresponding method parameter type is a primitive type; or if, after possible unboxing, any of theargs
elements cannot be assigned to the corresponding method parameter type.
IllegalAccessException
- if the declaring class of the specified default method is inaccessible to the caller classNullPointerException
- ifproxy
ormethod
isnull
Throwable
- anything thrown by the default method- See Java Virtual Machine Specification:
-
5.4.3. Method Resolution
- Since:
- 16
-