public class MethodDelegation extends Object implements Implementation.Composable
static
by providing
a reference to a Class
or an instance method when another object is provided. The potential
targets of the method delegation can further be filtered by applying a filter. The method delegation can be
customized by invoking the MethodDelegation
's several builder methods.
A method will be bound parameter by parameter. Considering a method
Foo#bar
being bound to a method
Qux#baz
, the method delegation will be decided on basis of the following annotations:
Argument
:
This annotation will bind the n
-th parameter of Foo#bar
to that parameter of Qux#baz
that
is annotated with this annotation where n
is the obligatory argument of the @Argument
annotation.AllArguments
:
This annotation will assign a collection of all parameters of Foo#bar
to that parameter of Qux#baz
that is annotated with AllArguments
.This
: A parameter
of Qux#baz
that is annotated with This
will be assigned the instance that is instrumented for
a non-static method.Super
: A parameter that is annotated with
this annotation is assigned a proxy that allows calling an instrumented type's super methods.Default
: A parameter that is annotated with
this annotation is assigned a proxy that allows calling an instrumented type's directly implemented interfaces'
default methods.SuperCall
: A parameter
of Qux#baz
that is annotated with SuperCall
will be assigned an instance of a type implementing both
Runnable
and Callable
which will invoke the instrumented method on the
invocation of either interface's method. The call is made using the original arguments of the method invocation.
The return value is only emitted for the Callable.call()
method which additionally
requires to catch any unchecked exceptions that might be thrown by the original method's implementation. If a
source method is abstract, using this annotation excludes the method with this parameter annotation from being bound
to this source method.
DefaultCall
:
This annotation is similar to the SuperCall
annotation but it invokes a default method that is compatible to this method. If a source method does not represent
a default method, using this annotation excludes the method with this parameter annotation from being bound to this
source method.Origin
: A parameter of
Qux#baz
that is annotated with Origin
is assigned a reference to either a Method
,
a Constructor
, a java.lang.reflect.Executable
or a Class
instance.
A Method
-typed, Constructor
or Executable
parameter is assigned a reference to the original
method that is instrumented. A Class
-typed parameter is assigned the type of the caller. Furthermore, MethodType
and MethodHandle
parameters are also supported. When using the annotation on a String
type,
the intercepted method's toString
value is injected. The same holds for a parameter of type int
that receives
the modifiers of the instrumented method.StubValue
: Assigns the (boxed) default value of the
intercepted method's return type to the parameter. If the return type is void
, null
is assigned.Empty
: Assigns the parameter type's
default value, i.e. null
for a reference type or zero for primitive types. This is an opportunity to
ignore a parameter.Pipe
: A parameter that is annotated
with this annotation is assigned a proxy for forwarding the source method invocation to another instance of the
same type as the declaring type of the intercepted method. This annotation needs to be installed and explicitly
registered before it can be used. See the Pipe
annotation's documentation for further information on how this can be done.Morph
: The morph annotation is similar to
the SuperCall
annotation but allows to
explicitly define and therewith alter the arguments that are handed to the super method. This annotation needs
to be installed and explicitly registered before it can be used. See the documentation to the annotation for
further information.FieldValue
: Allows to access a field's value at the time
of the method invocation. The field's value is directly assigned to the annotated parameter.FieldProxy
: Allows to access fields via getter
and setter proxies. This annotation needs to be installed and explicitly registered before it can be used.
Note that any field access requires boxing such that a use of FieldAccessor
in
combination with andThen(Implementation)
might be a more
performant alternative for implementing field getters and setters.Argument
using the next
unbound parameter index of the source method as its parameter. This means that a method
Qux#baz(@Argument(2) Object p1, Object p2, @Argument(0) Object p3
would be treated as if p2
was annotated
with @Argument(1)
.
In addition, the
RuntimeType
annotation can instruct a parameter to be bound by a
Assigner
with considering the
runtime type of the parameter.
Selecting among different methods that can be used for binding a method of the instrumented type
When deciding between two methods
Foo#bar
and Foo#qux
that could both be used to delegating a
method call, the following consideration is applied in the given order:
BindingPriority
:
A method that is annotated with this annotation is given a specific priority where the default priority is set
to BindingPriority.DEFAULT
for non-annotated method. A method with a higher priority is considered a better target for delegation.DeclaringTypeResolver
:
If a target method is declared by a more specific type than another method, the method with the most specific
type is bound.MethodNameEqualityResolver
:
If a source method Baz#qux
is the source method, it will rather be assigned to Foo#qux
because
of their equal names. Similar names and case-insensitive equality are not considered.ArgumentTypeResolver
:
The most specific type resolver will consider all bindings that are using the
Argument
annotation for resolving a binding conflict. In this context, the resolution will equal the most-specific
type resolution that is performed by the Java compiler. This means that a source method Bar#baz(String)
will rather be bound to a method Foo#bar(String)
than Foo#qux(Object)
because the String
type is more specific than the Object
type. If two methods are equally adequate by their parameter types,
then the method with the higher numbers of @Argument
annotated parameters is considered as the better
delegation target.ParameterLengthResolver
:
If a target methods has a higher number of total parameters that were successfully bound, the method with
the higher number will be considered as the better delegation target.
Additionally, if a method is annotated by
IgnoreForBinding
,
it is never considered as a target for a method delegation.
Important: For invoking a method on another instance, use the Forwarding
implementation. A method delegation
intends to bind a interceptor class and its resolution algorithm will not necessarily yield a delegation to the intercepted
method.
Forwarding
Modifier and Type | Class and Description |
---|---|
protected static class |
MethodDelegation.Appender
The appender for implementing a
MethodDelegation . |
protected static interface |
MethodDelegation.ImplementationDelegate
An implementation delegate is responsible for executing the actual method delegation.
|
protected static interface |
MethodDelegation.MethodContainer
A method container collects methods that are considered as a target for delegation.
|
Implementation.Composable, Implementation.Compound, Implementation.Context, Implementation.Simple, Implementation.SpecialMethodInvocation, Implementation.Target
Modifier | Constructor and Description |
---|---|
protected |
MethodDelegation(MethodDelegation.ImplementationDelegate implementationDelegate,
List<TargetMethodAnnotationDrivenBinder.ParameterBinder<?>> parameterBinders,
TargetMethodAnnotationDrivenBinder.DefaultsProvider defaultsProvider,
TargetMethodAnnotationDrivenBinder.TerminationHandler terminationHandler,
MethodDelegationBinder.AmbiguityResolver ambiguityResolver,
Assigner assigner,
MethodDelegation.MethodContainer methodContainer)
Creates a new method delegation.
|
Modifier and Type | Method and Description |
---|---|
Implementation |
andThen(Implementation implementation)
Appends the supplied implementation to this implementation.
|
MethodDelegation |
appendAmbiguityResolver(MethodDelegationBinder.AmbiguityResolver ambiguityResolver)
Defines an ambiguity resolver to be appended to the already defined ambiguity resolver for resolving binding conflicts.
|
ByteCodeAppender |
appender(Implementation.Target implementationTarget)
Creates a byte code appender that determines the implementation of the instrumented type's methods.
|
MethodDelegation |
appendParameterBinder(TargetMethodAnnotationDrivenBinder.ParameterBinder<?> parameterBinder)
Defines an parameter binder to be appended to the already defined parameter binders.
|
MethodDelegation |
defineAmbiguityResolver(MethodDelegationBinder.AmbiguityResolver... ambiguityResolver)
Defines an ambiguity resolver to be used for resolving binding conflicts.
|
MethodDelegation |
defineParameterBinder(TargetMethodAnnotationDrivenBinder.ParameterBinder<?>... parameterBinder)
Defines a number of parameter binders to be appended to be used by this method delegation.
|
boolean |
equals(Object other) |
MethodDelegation |
filter(ElementMatcher<? super MethodDescription> methodMatcher)
Applies a filter to target methods that are eligible for delegation.
|
int |
hashCode() |
InstrumentedType |
prepare(InstrumentedType instrumentedType)
Prepares a given instrumented type.
|
static MethodDelegation |
to(Class<?> type)
Creates an implementation where only
static methods of the given type are considered as binding targets. |
static MethodDelegation |
to(Object delegate)
Creates an implementation where only instance methods of the given object are considered as binding targets.
|
static MethodDelegation |
to(Object delegate,
MethodGraph.Compiler methodGraphCompiler)
Creates an implementation where only instance methods of the given object are considered as binding targets.
|
static MethodDelegation |
to(Object delegate,
String fieldName)
Creates an implementation where only instance methods of the given object are considered as binding targets.
|
static MethodDelegation |
to(Object delegate,
String fieldName,
MethodGraph.Compiler methodGraphCompiler)
Creates an implementation where only instance methods of the given object are considered as binding targets.
|
static MethodDelegation |
to(Object delegate,
Type type)
Creates an implementation where only instance methods of the given object are considered as binding targets.
|
static MethodDelegation |
to(Object delegate,
Type type,
MethodGraph.Compiler methodGraphCompiler)
Creates an implementation where only instance methods of the given object are considered as binding targets.
|
static MethodDelegation |
to(Object delegate,
Type type,
String fieldName)
Creates an implementation where only instance methods of the given object are considered as binding targets.
|
static MethodDelegation |
to(Object delegate,
Type type,
String fieldName,
MethodGraph.Compiler methodGraphCompiler)
Creates an implementation where only instance methods of the given object are considered as binding targets.
|
static MethodDelegation |
to(TypeDescription typeDescription)
Creates an implementation where only
static methods of the given type are considered as binding targets. |
static MethodDelegation |
toConstructor(Class<?> type)
Creates an implementation where method calls are delegated to constructor calls on the given type.
|
static MethodDelegation |
toConstructor(TypeDescription typeDescription)
Creates an implementation where method calls are delegated to constructor calls on the given type.
|
static MethodDelegation |
toInstanceField(Class<?> type,
String fieldName)
Creates an implementation where method calls are delegated to an instance that is manually stored in a field
fieldName that is defined for the instrumented type. |
static MethodDelegation |
toInstanceField(Class<?> type,
String fieldName,
MethodGraph.Compiler methodGraphCompiler)
Creates an implementation where method calls are delegated to an instance that is manually stored in a field
fieldName that is defined for the instrumented type. |
static MethodDelegation |
toInstanceField(TypeDefinition typeDefinition,
String fieldName,
MethodGraph.Compiler methodGraphCompiler)
Creates an implementation where method calls are delegated to an instance that is manually stored in a field
fieldName that is defined for the instrumented type. |
static MethodDelegation |
toInstanceField(TypeDescription typeDescription,
String fieldName)
Creates an implementation where method calls are delegated to an instance that is manually stored in a field
fieldName that is defined for the instrumented type. |
String |
toString() |
MethodDelegation |
withAssigner(Assigner assigner)
Applies an assigner to the method delegation that is used for assigning method return and parameter types.
|
MethodDelegation |
withDefaultsProvider(TargetMethodAnnotationDrivenBinder.DefaultsProvider defaultsProvider)
A provider for annotation instances on values that are not explicitly annotated.
|
protected MethodDelegation(MethodDelegation.ImplementationDelegate implementationDelegate, List<TargetMethodAnnotationDrivenBinder.ParameterBinder<?>> parameterBinders, TargetMethodAnnotationDrivenBinder.DefaultsProvider defaultsProvider, TargetMethodAnnotationDrivenBinder.TerminationHandler terminationHandler, MethodDelegationBinder.AmbiguityResolver ambiguityResolver, Assigner assigner, MethodDelegation.MethodContainer methodContainer)
implementationDelegate
- The implementation delegate to use by this method delegator.parameterBinders
- The parameter binders to use by this method delegator.defaultsProvider
- The defaults provider to use by this method delegator.terminationHandler
- The termination handler to apply.ambiguityResolver
- The ambiguity resolver to use by this method delegator.assigner
- The assigner to be supplied by this method delegator.methodContainer
- A method container to query for methods to be considered for delegation.public static MethodDelegation to(Class<?> type)
static
methods of the given type are considered as binding targets.type
- The type containing the static
methods for binding.static
methods.public static MethodDelegation to(TypeDescription typeDescription)
static
methods of the given type are considered as binding targets.typeDescription
- The type containing the static
methods for binding.static
methods.public static MethodDelegation to(Object delegate)
Object
class. You can narrow this default
selection by explicitly selecting methods with calling the
filter(net.bytebuddy.matcher.ElementMatcher)
method on the returned method delegation as for example:
MethodDelegation.to(new Foo()).filter(MethodMatchers.not(isDeclaredBy(Object.class)));which will result in a delegation to
Foo
where no methods of Object
are considered
for delegation.delegate
- A delegate instance which will be injected by a
LoadedTypeInitializer
. All intercepted method calls are
then delegated to this instance.public static MethodDelegation to(Object delegate, MethodGraph.Compiler methodGraphCompiler)
Object
class. You can narrow this default
selection by explicitly selecting methods with calling the
filter(net.bytebuddy.matcher.ElementMatcher)
method on the returned method delegation as for example:
MethodDelegation.to(new Foo()).filter(MethodMatchers.not(isDeclaredBy(Object.class)));which will result in a delegation to
Foo
where no methods of Object
are considered
for delegation.delegate
- A delegate instance which will be injected by a
LoadedTypeInitializer
. All intercepted method calls are
then delegated to this instance.methodGraphCompiler
- The method graph compiler to be used for locating methods to delegate to.public static MethodDelegation to(Object delegate, String fieldName)
Object
class. You can narrow this default
selection by explicitly selecting methods with calling the
filter(net.bytebuddy.matcher.ElementMatcher)
method on the returned method delegation as for example:
MethodDelegation.to(new Foo()).filter(MethodMatchers.not(isDeclaredBy(Object.class)));which will result in a delegation to
Foo
where no methods of Object
are considered
for delegation.delegate
- A delegate instance which will be injected by a
LoadedTypeInitializer
. All intercepted method calls are
then delegated to this instance.fieldName
- The name of the field for storing the delegate instance.static
methods.public static MethodDelegation to(Object delegate, String fieldName, MethodGraph.Compiler methodGraphCompiler)
Object
class. You can narrow this default
selection by explicitly selecting methods with calling the
filter(net.bytebuddy.matcher.ElementMatcher)
method on the returned method delegation as for example:
MethodDelegation.to(new Foo()).filter(MethodMatchers.not(isDeclaredBy(Object.class)));which will result in a delegation to
Foo
where no methods of Object
are considered
for delegation.delegate
- A delegate instance which will be injected by a
LoadedTypeInitializer
. All intercepted method calls are
then delegated to this instance.fieldName
- The name of the field for storing the delegate instance.methodGraphCompiler
- The method graph compiler to be used for locating methods to delegate to.static
methods.public static MethodDelegation to(Object delegate, Type type)
Object
class. You can narrow this default
selection by explicitly selecting methods with calling the
filter(net.bytebuddy.matcher.ElementMatcher)
method on the returned method delegation as for example:
MethodDelegation.to(new Foo()).filter(MethodMatchers.not(isDeclaredBy(Object.class)));which will result in a delegation to
Foo
where no methods of Object
are considered
for delegation.delegate
- A delegate instance which will be injected by a
LoadedTypeInitializer
. All intercepted method calls are
then delegated to this instance.type
- The type as which the delegate is treated for resolving its methods.public static MethodDelegation to(Object delegate, Type type, MethodGraph.Compiler methodGraphCompiler)
Object
class. You can narrow this default
selection by explicitly selecting methods with calling the
filter(net.bytebuddy.matcher.ElementMatcher)
method on the returned method delegation as for example:
MethodDelegation.to(new Foo()).filter(MethodMatchers.not(isDeclaredBy(Object.class)));which will result in a delegation to
Foo
where no methods of Object
are considered
for delegation.delegate
- A delegate instance which will be injected by a
LoadedTypeInitializer
. All intercepted method calls are
then delegated to this instance.type
- The type as which the delegate is treated for resolving its methods.methodGraphCompiler
- The method graph compiler to be used for locating methods to delegate to.public static MethodDelegation to(Object delegate, Type type, String fieldName)
Object
class. You can narrow this default
selection by explicitly selecting methods with calling the
filter(net.bytebuddy.matcher.ElementMatcher)
method on the returned method delegation as for example:
MethodDelegation.to(new Foo()).filter(MethodMatchers.not(isDeclaredBy(Object.class)));which will result in a delegation to
Foo
where no methods of Object
are considered
for delegation.delegate
- A delegate instance which will be injected by a
LoadedTypeInitializer
. All intercepted method calls are
then delegated to this instance.type
- The type as which the delegate is treated for resolving its methods.fieldName
- The name of the field for storing the delegate instance.static
methods.public static MethodDelegation to(Object delegate, Type type, String fieldName, MethodGraph.Compiler methodGraphCompiler)
Object
class. You can narrow this default
selection by explicitly selecting methods with calling the
filter(net.bytebuddy.matcher.ElementMatcher)
method on the returned method delegation as for example:
MethodDelegation.to(new Foo()).filter(MethodMatchers.not(isDeclaredBy(Object.class)));which will result in a delegation to
Foo
where no methods of Object
are considered
for delegation.delegate
- A delegate instance which will be injected by a
LoadedTypeInitializer
. All intercepted method calls are
then delegated to this instance.type
- The type as which the delegate is treated for resolving its methods.fieldName
- The name of the field for storing the delegate instance.methodGraphCompiler
- The method graph compiler to be used for locating methods to delegate to.static
methods.public static MethodDelegation toInstanceField(Class<?> type, String fieldName)
fieldName
that is defined for the instrumented type. The field belongs to any instance of the instrumented
type and must be set manually by the user of the instrumented class. Note that this prevents interception of
method calls within the constructor of the instrumented class which will instead result in a
NullPointerException
. Note that this includes methods that were defined by the
Object
class. You can narrow this default selection by explicitly selecting methods with
calling the
filter(net.bytebuddy.matcher.ElementMatcher)
method on the returned method delegation as for example:
MethodDelegation.to(new Foo()).filter(MethodMatchers.not(isDeclaredBy(Object.class)));which will result in a delegation to
Foo
where no methods of Object
are considered
for delegation.
The field is typically accessed by reflection or by defining an accessor on the instrumented type.
type
- The type of the delegate and the field.fieldName
- The name of the field.public static MethodDelegation toInstanceField(TypeDescription typeDescription, String fieldName)
fieldName
that is defined for the instrumented type. The field belongs to any instance of the instrumented
type and must be set manually by the user of the instrumented class. Note that this prevents interception of
method calls within the constructor of the instrumented class which will instead result in a
NullPointerException
. Note that this includes methods that were defined by the
Object
class. You can narrow this default selection by explicitly selecting methods with
calling the
filter(net.bytebuddy.matcher.ElementMatcher)
method on the returned method delegation as for example:
MethodDelegation.to(new Foo()).filter(MethodMatchers.not(isDeclaredBy(Object.class)));which will result in a delegation to
Foo
where no methods of Object
are considered
for delegation.
The field is typically accessed by reflection or by defining an accessor on the instrumented type.
typeDescription
- The type of the delegate and the field.fieldName
- The name of the field.public static MethodDelegation toInstanceField(Class<?> type, String fieldName, MethodGraph.Compiler methodGraphCompiler)
fieldName
that is defined for the instrumented type. The field belongs to any instance of the instrumented
type and must be set manually by the user of the instrumented class. Note that this prevents interception of
method calls within the constructor of the instrumented class which will instead result in a
NullPointerException
. Note that this includes methods that were defined by the
Object
class. You can narrow this default selection by explicitly selecting methods with
calling the
filter(net.bytebuddy.matcher.ElementMatcher)
method on the returned method delegation as for example:
MethodDelegation.to(new Foo()).filter(MethodMatchers.not(isDeclaredBy(Object.class)));which will result in a delegation to
Foo
where no methods of Object
are considered
for delegation.
The field is typically accessed by reflection or by defining an accessor on the instrumented type.
type
- The type of the delegate and the field.fieldName
- The name of the field.methodGraphCompiler
- The method graph compiler to be used for locating methods to delegate to.public static MethodDelegation toInstanceField(TypeDefinition typeDefinition, String fieldName, MethodGraph.Compiler methodGraphCompiler)
fieldName
that is defined for the instrumented type. The field belongs to any instance of the instrumented
type and must be set manually by the user of the instrumented class. Note that this prevents interception of
method calls within the constructor of the instrumented class which will instead result in a
NullPointerException
. Note that this includes methods that were defined by the
Object
class. You can narrow this default selection by explicitly selecting methods with
calling the
filter(net.bytebuddy.matcher.ElementMatcher)
method on the returned method delegation as for example:
MethodDelegation.to(new Foo()).filter(MethodMatchers.not(isDeclaredBy(Object.class)));which will result in a delegation to
Foo
where no methods of Object
are considered
for delegation.
The field is typically accessed by reflection or by defining an accessor on the instrumented type.
typeDefinition
- The type of the delegate and the field.fieldName
- The name of the field.methodGraphCompiler
- The method graph compiler to be used for locating methods to delegate to.public static MethodDelegation toConstructor(Class<?> type)
type
- The type that should be constructed by the instrumented methods.public static MethodDelegation toConstructor(TypeDescription typeDescription)
typeDescription
- The type that should be constructed by the instrumented methods.public MethodDelegation appendParameterBinder(TargetMethodAnnotationDrivenBinder.ParameterBinder<?> parameterBinder)
parameterBinder
- The parameter binder to append to the already defined parameter binders.public MethodDelegation defineParameterBinder(TargetMethodAnnotationDrivenBinder.ParameterBinder<?>... parameterBinder)
parameterBinder
- The parameter binders to use by this parameter binders.public MethodDelegation withDefaultsProvider(TargetMethodAnnotationDrivenBinder.DefaultsProvider defaultsProvider)
defaultsProvider
- The defaults provider to use.public MethodDelegation appendAmbiguityResolver(MethodDelegationBinder.AmbiguityResolver ambiguityResolver)
ambiguityResolver
- The ambiguity resolver to append to the already defined ambiguity resolvers.public MethodDelegation defineAmbiguityResolver(MethodDelegationBinder.AmbiguityResolver... ambiguityResolver)
ambiguityResolver
- The ambiguity resolver to use exclusively.public MethodDelegation withAssigner(Assigner assigner)
assigner
- The assigner to apply.public MethodDelegation filter(ElementMatcher<? super MethodDescription> methodMatcher)
methodMatcher
- A filter where only methods that match the filter are considered for delegation.public Implementation andThen(Implementation implementation)
Implementation.Composable
andThen
in interface Implementation.Composable
implementation
- The subsequent implementation.public InstrumentedType prepare(InstrumentedType instrumentedType)
InstrumentedType.Prepareable
prepare
in interface InstrumentedType.Prepareable
instrumentedType
- The instrumented type in its current form.public ByteCodeAppender appender(Implementation.Target implementationTarget)
Implementation
appender
in interface Implementation
implementationTarget
- The target of the current implementation.InstrumentedType.Prepareable.prepare(InstrumentedType)
.Copyright © 2014–2016. All rights reserved.