public class MethodDelegation extends Object implements Instrumentation
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#bazthat
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
or a Class instance. A Method-typed parameter is assigned a reference to the original method that
is overriden. A Class-typed parameter is assigned the type of the caller.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.Field: 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(Instrumentation) 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.IgnoreForBinding,
it is never considered as a target for a method delegation.| Modifier and Type | Class and Description |
|---|---|
protected static class |
MethodDelegation.Appender
The appender for implementing a
MethodDelegation. |
protected static interface |
MethodDelegation.InstrumentationDelegate
An instrumentation delegate is responsible for executing the actual method delegation.
|
Instrumentation.Compound, Instrumentation.Context, Instrumentation.ForAbstractMethod, Instrumentation.Simple, Instrumentation.SpecialMethodInvocation, Instrumentation.Target| Modifier | Constructor and Description |
|---|---|
protected |
MethodDelegation(MethodDelegation.InstrumentationDelegate instrumentationDelegate,
List<TargetMethodAnnotationDrivenBinder.ParameterBinder<?>> parameterBinders,
TargetMethodAnnotationDrivenBinder.DefaultsProvider defaultsProvider,
TargetMethodAnnotationDrivenBinder.TerminationHandler terminationHandler,
MethodDelegationBinder.AmbiguityResolver ambiguityResolver,
Assigner assigner,
MethodList targetMethodCandidates)
Creates a new method delegation.
|
| Modifier and Type | Method and Description |
|---|---|
Instrumentation |
andThen(Instrumentation instrumentation)
Appends another
Instrumentation to a method delegation. |
MethodDelegation |
appendAmbiguityResolver(MethodDelegationBinder.AmbiguityResolver ambiguityResolver)
Defines an ambiguity resolver to be appended to the already defined ambiguity resolver for resolving binding conflicts.
|
ByteCodeAppender |
appender(Instrumentation.Target instrumentationTarget)
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)
During the preparation phase of an instrumentation, implementations are eligible to adding fields or methods
to the currently instrumented type.
|
static MethodDelegation |
to(Class<?> type)
Creates an instrumentation where only
static methods of the given type are considered as binding targets. |
static MethodDelegation |
to(Object delegate)
Creates an instrumentation where only instance methods of the given object are considered as binding targets.
|
static MethodDelegation |
to(Object delegate,
MethodLookupEngine methodLookupEngine)
Identical to
to(Object) but uses an explicit
MethodLookupEngine. |
static MethodDelegation |
to(Object delegate,
String fieldName)
Creates an instrumentation where only instance methods of the given object are considered as binding targets.
|
static MethodDelegation |
to(Object delegate,
String fieldName,
MethodLookupEngine methodLookupEngine)
Identical to
to(Object, java.lang.String) but uses an
explicit MethodLookupEngine. |
static MethodDelegation |
to(TypeDescription typeDescription)
Creates an instrumentation where only
static methods of the given type are considered as binding targets. |
static MethodDelegation |
toConstructor(Class<?> type)
Creates an instrumentation where method calls are delegated to constructor calls on the given type.
|
static MethodDelegation |
toConstructor(TypeDescription typeDescription)
Creates an instrumentation where method calls are delegated to constructor calls on the given type.
|
static MethodDelegation |
toInstanceField(Class<?> type,
String fieldName)
Creates an instrumentation 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,
MethodLookupEngine methodLookupEngine)
Identical to
toInstanceField(Class, String) but uses an
explicit MethodLookupEngine. |
static MethodDelegation |
toInstanceField(TypeDescription typeDescription,
String fieldName)
Creates an instrumentation 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,
MethodLookupEngine methodLookupEngine)
Identical to
toInstanceField(Class, String) but uses an
explicit MethodLookupEngine. |
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.InstrumentationDelegate instrumentationDelegate, List<TargetMethodAnnotationDrivenBinder.ParameterBinder<?>> parameterBinders, TargetMethodAnnotationDrivenBinder.DefaultsProvider defaultsProvider, TargetMethodAnnotationDrivenBinder.TerminationHandler terminationHandler, MethodDelegationBinder.AmbiguityResolver ambiguityResolver, Assigner assigner, MethodList targetMethodCandidates)
instrumentationDelegate - The instrumentation 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.targetMethodCandidates - A list of methods that should be considered as possible binding targets by
this method delegator.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, MethodLookupEngine methodLookupEngine)
to(Object) but uses an explicit
MethodLookupEngine.delegate - A delegate instance which will be injected by a
LoadedTypeInitializer. All intercepted method
calls are then delegated to this instance.methodLookupEngine - The method lookup engine to use.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, MethodLookupEngine methodLookupEngine)
to(Object, java.lang.String) but uses an
explicit MethodLookupEngine.delegate - A delegate instance which will be injected by a type initializer and to which all intercepted
method calls are delegated to.fieldName - The name of the field for storing the delegate instance.methodLookupEngine - The method lookup engine to use.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, MethodLookupEngine methodLookupEngine)
toInstanceField(Class, String) but uses an
explicit MethodLookupEngine.type - The type of the delegate and the field.fieldName - The name of the field.methodLookupEngine - The method lookup engine to use.public static MethodDelegation toInstanceField(TypeDescription typeDescription, String fieldName, MethodLookupEngine methodLookupEngine)
toInstanceField(Class, String) but uses an
explicit MethodLookupEngine.typeDescription - The type of the delegate and the field.fieldName - The name of the field.methodLookupEngine - The method lookup engine to use.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 Instrumentation andThen(Instrumentation instrumentation)
Instrumentation to a method delegation. The return
value of the delegation target is dropped such that the given instrumentation becomes responsible for
returning from the method instead. However, if an exception is thrown from the interception method, this
exception is not catched and the chained instrumentation is never applied. Note that this changes the binding
semantics as the target method's return value is not longer considered what might change the binding target.instrumentation - The instrumentation to apply after the delegation.public InstrumentedType prepare(InstrumentedType instrumentedType)
InstrumentationByteCodeAppender that is emitted
on the call to
Instrumentation.appender(net.bytebuddy.instrumentation.Instrumentation.Target)
call. On this method call, loaded type initializers can also be added to the instrumented type.prepare in interface InstrumentationinstrumentedType - The instrumented type that is the basis of the ongoing instrumentation.public ByteCodeAppender appender(Instrumentation.Target instrumentationTarget)
Instrumentationappender in interface InstrumentationinstrumentationTarget - The target of the current instrumentation.Instrumentation.prepare(net.bytebuddy.instrumentation.type.InstrumentedType).Copyright © 2014. All rights reserved.