@HashCodeAndEqualsPlugin.Enhance 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.
Without any customization, the method delegation will work as follows:
Binding an instrumented method to a given delegate method
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. For using method handles, the SuperCallHandle
and DefaultCallHandle annotations can be used.SuperMethod or
DefaultMethod annotations can be used on any parameter type
that is assignable from the Method type. the parameter is bound a method instance that
allows for the reflective invocation of a super or default method. Note that this method is not equal to the intercepted
method but represents a synthetic accessor method. Using this annotation also causes this accessor to be public
which allows its outside invocation without any access checks by a security manager. For using method handles, the
SuperCallHandle and
DefaultCallHandle annotations can be used.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 MethodCall implementation. A method delegation
intends to bind a interceptor class and its resolution algorithm will not necessarily yield a delegation to the intercepted
method.
| 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 and for resolving the target methods.
|
static class |
MethodDelegation.WithCustomProperties
A
MethodDelegation with custom configuration. |
Implementation.Composable, Implementation.Compound, Implementation.Context, Implementation.Simple, Implementation.SpecialMethodInvocation, Implementation.TargetInstrumentedType.Prepareable.NoOp| Modifier | Constructor and Description |
|---|---|
protected |
MethodDelegation(MethodDelegation.ImplementationDelegate implementationDelegate,
List<TargetMethodAnnotationDrivenBinder.ParameterBinder<?>> parameterBinders,
MethodDelegationBinder.AmbiguityResolver ambiguityResolver,
MethodDelegationBinder.BindingResolver bindingResolver)
Creates a new method delegation.
|
| Modifier and Type | Method and Description |
|---|---|
Implementation.Composable |
andThen(Implementation.Composable implementation)
Appends the supplied composable implementation to this implementation.
|
Implementation |
andThen(Implementation implementation)
Appends the supplied implementation to this implementation.
|
ByteCodeAppender |
appender(Implementation.Target implementationTarget)
Creates a byte code appender that determines the implementation of the instrumented type's methods.
|
InstrumentedType |
prepare(InstrumentedType instrumentedType)
Prepares a given instrumented type.
|
static MethodDelegation |
to(Class<?> type)
Delegates any intercepted method to invoke a
static method that is declared by the supplied type. |
static MethodDelegation |
to(Object target)
Delegates any intercepted method to invoke a non-
static method that is declared by the supplied type's instance or any
of its super types. |
static MethodDelegation |
to(Object target,
MethodGraph.Compiler methodGraphCompiler)
Delegates any intercepted method to invoke a non-
static method that is declared by the supplied type's instance or any
of its super types. |
static MethodDelegation |
to(Object target,
String fieldName)
Delegates any intercepted method to invoke a non-
static method that is declared by the supplied type's instance or any
of its super types. |
static MethodDelegation |
to(Object target,
String fieldName,
MethodGraph.Compiler methodGraphCompiler)
Delegates any intercepted method to invoke a non-
static method that is declared by the supplied type's instance or any
of its super types. |
static MethodDelegation |
to(Object target,
Type type)
Delegates any intercepted method to invoke a non-
static method that is declared by the supplied type's instance or any
of its super types. |
static MethodDelegation |
to(Object target,
TypeDefinition typeDefinition)
Delegates any intercepted method to invoke a non-
static method that is declared by the supplied type's instance or any
of its super types. |
static MethodDelegation |
to(Object target,
TypeDefinition typeDefinition,
MethodGraph.Compiler methodGraphCompiler)
Delegates any intercepted method to invoke a non-
static method that is declared by the supplied type's instance or any
of its super types. |
static MethodDelegation |
to(Object target,
TypeDefinition typeDefinition,
String fieldName)
Delegates any intercepted method to invoke a non-
static method that is declared by the supplied type's instance or any
of its super types. |
static MethodDelegation |
to(Object target,
TypeDefinition typeDefinition,
String fieldName,
MethodGraph.Compiler methodGraphCompiler)
Delegates any intercepted method to invoke a non-
static method that is declared by the supplied type's instance or any
of its super types. |
static MethodDelegation |
to(Object target,
Type type,
MethodGraph.Compiler methodGraphCompiler)
Delegates any intercepted method to invoke a non-
static method that is declared by the supplied type's instance or any
of its super types. |
static MethodDelegation |
to(Object target,
Type type,
String fieldName)
Delegates any intercepted method to invoke a non-
static method that is declared by the supplied type's instance or any
of its super types. |
static MethodDelegation |
to(Object target,
Type type,
String fieldName,
MethodGraph.Compiler methodGraphCompiler)
Delegates any intercepted method to invoke a non-
static method that is declared by the supplied type's instance or any
of its super types. |
static MethodDelegation |
to(TypeDescription typeDescription)
Delegates any intercepted method to invoke a
static method that is declared by the supplied type. |
static MethodDelegation |
toConstructor(Class<?> type)
Delegates any intercepted method to invoke a constructor of the supplied type.
|
static MethodDelegation |
toConstructor(TypeDescription typeDescription)
Delegates any intercepted method to invoke a constructor of the supplied type.
|
static MethodDelegation |
toField(String name)
Delegates any intercepted method to invoke a non-
static method on the instance of the supplied field. |
static MethodDelegation |
toField(String name,
FieldLocator.Factory fieldLocatorFactory)
Delegates any intercepted method to invoke a non-
static method on the instance of the supplied field. |
static MethodDelegation |
toField(String name,
FieldLocator.Factory fieldLocatorFactory,
MethodGraph.Compiler methodGraphCompiler)
Delegates any intercepted method to invoke a non-
static method on the instance of the supplied field. |
static MethodDelegation |
toField(String name,
MethodGraph.Compiler methodGraphCompiler)
Delegates any intercepted method to invoke a non-
static method on the instance of the supplied field. |
static MethodDelegation |
toMethodReturnOf(String name)
Delegates any intercepted method to invoke a method on an instance that is returned by a parameterless method of the
given name.
|
static MethodDelegation |
toMethodReturnOf(String name,
MethodGraph.Compiler methodGraphCompiler)
Delegates any intercepted method to invoke a method on an instance that is returned by a parameterless method of the
given name.
|
Implementation.Composable |
withAssigner(Assigner assigner)
Applies an assigner to the method delegation that is used for assigning method return and parameter types.
|
static MethodDelegation.WithCustomProperties |
withDefaultConfiguration()
Creates a configuration builder for a method delegation that is pre-configured with the ambiguity resolvers defined by
MethodDelegationBinder.AmbiguityResolver.DEFAULT and the parameter binders
defined by TargetMethodAnnotationDrivenBinder.ParameterBinder.DEFAULTS. |
static MethodDelegation.WithCustomProperties |
withEmptyConfiguration()
Creates a configuration builder for a method delegation that does not apply any pre-configured
MethodDelegationBinder.AmbiguityResolvers or
TargetMethodAnnotationDrivenBinder.ParameterBinders. |
protected MethodDelegation(MethodDelegation.ImplementationDelegate implementationDelegate, List<TargetMethodAnnotationDrivenBinder.ParameterBinder<?>> parameterBinders, MethodDelegationBinder.AmbiguityResolver ambiguityResolver, MethodDelegationBinder.BindingResolver bindingResolver)
implementationDelegate - The implementation delegate to use by this method delegator.parameterBinders - The parameter binders to use by this method delegator.ambiguityResolver - The ambiguity resolver to use by this method delegator.bindingResolver - The binding resolver being used to select the relevant method binding.public static MethodDelegation to(Class<?> type)
static method that is declared by the supplied type. To be considered
a valid delegation target, the target method must be visible and accessible to the instrumented type. This is the case if
the target type is either public or in the same package as the instrumented type and if the target method is either public
or non-private and in the same package as the instrumented type. Private methods can only be used as a delegation target if
the interception is targeting the instrumented type.type - The target type for the delegation.public static MethodDelegation to(TypeDescription typeDescription)
static method that is declared by the supplied type. To be considered
a valid delegation target, the target method must be visible and accessible to the instrumented type. This is the case if
the target type is either public or in the same package as the instrumented type and if the target method is either public
or non-private and in the same package as the instrumented type. Private methods can only be used as a delegation target if
the interception is targeting the instrumented type.typeDescription - The target type for the delegation.public static MethodDelegation to(Object target)
static method that is declared by the supplied type's instance or any
of its super types. To be considered a valid delegation target, a method must be visible and accessible to the instrumented type.
This is the case if the method's declaring type is either public or in the same package as the instrumented type and if the method
is either public or non-private and in the same package as the instrumented type. Private methods can only be used as
a delegation target if the delegation is targeting the instrumented type.target - The target instance for the delegation.public static MethodDelegation to(Object target, MethodGraph.Compiler methodGraphCompiler)
static method that is declared by the supplied type's instance or any
of its super types. To be considered a valid delegation target, a method must be visible and accessible to the instrumented type.
This is the case if the method's declaring type is either public or in the same package as the instrumented type and if the method
is either public or non-private and in the same package as the instrumented type. Private methods can only be used as
a delegation target if the delegation is targeting the instrumented type.target - The target instance for the delegation.methodGraphCompiler - The method graph compiler to use.public static MethodDelegation to(Object target, String fieldName)
static method that is declared by the supplied type's instance or any
of its super types. To be considered a valid delegation target, a method must be visible and accessible to the instrumented type.
This is the case if the method's declaring type is either public or in the same package as the instrumented type and if the method
is either public or non-private and in the same package as the instrumented type. Private methods can only be used as
a delegation target if the delegation is targeting the instrumented type.target - The target instance for the delegation.fieldName - The name of the field that is holding the target instance.public static MethodDelegation to(Object target, String fieldName, MethodGraph.Compiler methodGraphCompiler)
static method that is declared by the supplied type's instance or any
of its super types. To be considered a valid delegation target, a method must be visible and accessible to the instrumented type.
This is the case if the method's declaring type is either public or in the same package as the instrumented type and if the method
is either public or non-private and in the same package as the instrumented type. Private methods can only be used as
a delegation target if the delegation is targeting the instrumented type.target - The target instance for the delegation.fieldName - The name of the field that is holding the target instance.methodGraphCompiler - The method graph compiler to use.public static MethodDelegation to(Object target, Type type)
static method that is declared by the supplied type's instance or any
of its super types. To be considered a valid delegation target, a method must be visible and accessible to the instrumented type.
This is the case if the method's declaring type is either public or in the same package as the instrumented type and if the method
is either public or non-private and in the same package as the instrumented type. Private methods can only be used as
a delegation target if the delegation is targeting the instrumented type.target - The target instance for the delegation.type - The most specific type of which target should be considered. Must be a super type of the target's actual type.public static MethodDelegation to(Object target, Type type, MethodGraph.Compiler methodGraphCompiler)
static method that is declared by the supplied type's instance or any
of its super types. To be considered a valid delegation target, a method must be visible and accessible to the instrumented type.
This is the case if the method's declaring type is either public or in the same package as the instrumented type and if the method
is either public or non-private and in the same package as the instrumented type. Private methods can only be used as
a delegation target if the delegation is targeting the instrumented type.target - The target instance for the delegation.type - The most specific type of which target should be considered. Must be a super type of the target's actual type.methodGraphCompiler - The method graph compiler to use.public static MethodDelegation to(Object target, Type type, String fieldName)
static method that is declared by the supplied type's instance or any
of its super types. To be considered a valid delegation target, a method must be visible and accessible to the instrumented type.
This is the case if the method's declaring type is either public or in the same package as the instrumented type and if the method
is either public or non-private and in the same package as the instrumented type. Private methods can only be used as
a delegation target if the delegation is targeting the instrumented type.target - The target instance for the delegation.type - The most specific type of which target should be considered. Must be a super type of the target's actual type.fieldName - The name of the field that is holding the target instance.public static MethodDelegation to(Object target, Type type, String fieldName, MethodGraph.Compiler methodGraphCompiler)
static method that is declared by the supplied type's instance or any
of its super types. To be considered a valid delegation target, a method must be visible and accessible to the instrumented type.
This is the case if the method's declaring type is either public or in the same package as the instrumented type and if the method
is either public or non-private and in the same package as the instrumented type. Private methods can only be used as
a delegation target if the delegation is targeting the instrumented type.target - The target instance for the delegation.type - The most specific type of which target should be considered. Must be a super type of the target's actual type.fieldName - The name of the field that is holding the target instance.methodGraphCompiler - The method graph compiler to use.public static MethodDelegation to(Object target, TypeDefinition typeDefinition)
static method that is declared by the supplied type's instance or any
of its super types. To be considered a valid delegation target, a method must be visible and accessible to the instrumented type.
This is the case if the method's declaring type is either public or in the same package as the instrumented type and if the method
is either public or non-private and in the same package as the instrumented type. Private methods can only be used as
a delegation target if the delegation is targeting the instrumented type.target - The target instance for the delegation.typeDefinition - The most specific type of which target should be considered. Must be a super type of the target's actual type.public static MethodDelegation to(Object target, TypeDefinition typeDefinition, MethodGraph.Compiler methodGraphCompiler)
static method that is declared by the supplied type's instance or any
of its super types. To be considered a valid delegation target, a method must be visible and accessible to the instrumented type.
This is the case if the method's declaring type is either public or in the same package as the instrumented type and if the method
is either public or non-private and in the same package as the instrumented type. Private methods can only be used as
a delegation target if the delegation is targeting the instrumented type.target - The target instance for the delegation.typeDefinition - The most specific type of which target should be considered. Must be a super type of the target's actual type.methodGraphCompiler - The method graph compiler to use.public static MethodDelegation to(Object target, TypeDefinition typeDefinition, String fieldName)
static method that is declared by the supplied type's instance or any
of its super types. To be considered a valid delegation target, a method must be visible and accessible to the instrumented type.
This is the case if the method's declaring type is either public or in the same package as the instrumented type and if the method
is either public or non-private and in the same package as the instrumented type. Private methods can only be used as
a delegation target if the delegation is targeting the instrumented type.target - The target instance for the delegation.typeDefinition - The most specific type of which target should be considered. Must be a super type of the target's actual type.fieldName - The name of the field that is holding the target instance.public static MethodDelegation to(Object target, TypeDefinition typeDefinition, String fieldName, MethodGraph.Compiler methodGraphCompiler)
static method that is declared by the supplied type's instance or any
of its super types. To be considered a valid delegation target, a method must be visible and accessible to the instrumented type.
This is the case if the method's declaring type is either public or in the same package as the instrumented type and if the method
is either public or non-private and in the same package as the instrumented type. Private methods can only be used as
a delegation target if the delegation is targeting the instrumented type.target - The target instance for the delegation.typeDefinition - The most specific type of which target should be considered. Must be a super type of the target's actual type.fieldName - The name of the field that is holding the target instance.methodGraphCompiler - The method graph compiler to use.public static MethodDelegation toConstructor(Class<?> type)
type - The type to construct.public static MethodDelegation toConstructor(TypeDescription typeDescription)
typeDescription - The type to construct.public static MethodDelegation toField(String name)
static method on the instance of the supplied field. To be
considered a valid delegation target, a method must be visible and accessible to the instrumented type. This is the
case if the method's declaring type is either public or in the same package as the instrumented type and if the method
is either public or non-private and in the same package as the instrumented type. Private methods can only be used as
a delegation target if the delegation is targeting the instrumented type.name - The field's name.public static MethodDelegation toField(String name, FieldLocator.Factory fieldLocatorFactory)
static method on the instance of the supplied field. To be
considered a valid delegation target, a method must be visible and accessible to the instrumented type. This is the
case if the method's declaring type is either public or in the same package as the instrumented type and if the method
is either public or non-private and in the same package as the instrumented type. Private methods can only be used as
a delegation target if the delegation is targeting the instrumented type.name - The field's name.fieldLocatorFactory - The field locator factory to use.public static MethodDelegation toField(String name, MethodGraph.Compiler methodGraphCompiler)
static method on the instance of the supplied field. To be
considered a valid delegation target, a method must be visible and accessible to the instrumented type. This is the
case if the method's declaring type is either public or in the same package as the instrumented type and if the method
is either public or non-private and in the same package as the instrumented type. Private methods can only be used as
a delegation target if the delegation is targeting the instrumented type.name - The field's name.methodGraphCompiler - The method graph compiler to use.public static MethodDelegation toField(String name, FieldLocator.Factory fieldLocatorFactory, MethodGraph.Compiler methodGraphCompiler)
static method on the instance of the supplied field. To be
considered a valid delegation target, a method must be visible and accessible to the instrumented type. This is the
case if the method's declaring type is either public or in the same package as the instrumented type and if the method
is either public or non-private and in the same package as the instrumented type. Private methods can only be used as
a delegation target if the delegation is targeting the instrumented type.name - The field's name.fieldLocatorFactory - The field locator factory to use.methodGraphCompiler - The method graph compiler to use.public static MethodDelegation toMethodReturnOf(String name)
name - The name of the method that returns the delegation target.public static MethodDelegation toMethodReturnOf(String name, MethodGraph.Compiler methodGraphCompiler)
name - The name of the method that returns the delegation target.methodGraphCompiler - The method graph compiler to use.public static MethodDelegation.WithCustomProperties withDefaultConfiguration()
MethodDelegationBinder.AmbiguityResolver.DEFAULT and the parameter binders
defined by TargetMethodAnnotationDrivenBinder.ParameterBinder.DEFAULTS.public static MethodDelegation.WithCustomProperties withEmptyConfiguration()
MethodDelegationBinder.AmbiguityResolvers or
TargetMethodAnnotationDrivenBinder.ParameterBinders.public Implementation.Composable withAssigner(Assigner assigner)
assigner - The assigner to apply.public Implementation andThen(Implementation implementation)
andThen in interface Implementation.Composableimplementation - The subsequent implementation.public Implementation.Composable andThen(Implementation.Composable implementation)
andThen in interface Implementation.Composableimplementation - The subsequent composable implementation.public InstrumentedType prepare(InstrumentedType instrumentedType)
prepare in interface InstrumentedType.PrepareableinstrumentedType - The instrumented type in its current form.public ByteCodeAppender appender(Implementation.Target implementationTarget)
appender in interface ImplementationimplementationTarget - The target of the current implementation.InstrumentedType.Prepareable.prepare(InstrumentedType).Copyright © 2014–2024. All rights reserved.