Package net.bytebuddy.implementation

Class MethodDelegation

java.lang.Object
net.bytebuddy.implementation.MethodDelegation
All Implemented Interfaces:
InstrumentedType.Prepareable, Implementation, Implementation.Composable
@Enhance public class MethodDelegation extends Object implements Implementation.Composable
This implementation delegates a method call to another method which can either be 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.
  • SuperCall: This annotation is similar to the DefaultCall 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.
  • The 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.
If a method is not annotated with any of the above methods, it will be treated as if it was annotated 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:
  1. 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.
  2. DeclaringTypeResolver: If a target method is declared by a more specific type than another method, the method with the most specific type is bound.
  3. 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.
  4. 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.
  5. 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.

See Also:

  • Field Details

  • Constructor Details

  • Method Details

    • to

      public static MethodDelegation to(Class<?> type)
      Delegates any intercepted method to invoke a 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.
      Parameters:
      type - The target type for the delegation.
      Returns:
      A method delegation that redirects method calls to a static method of the supplied type.

    • to

      public static MethodDelegation to(TypeDescription typeDescription)
      Delegates any intercepted method to invoke a 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.
      Parameters:
      typeDescription - The target type for the delegation.
      Returns:
      A method delegation that redirects method calls to a static method of the supplied type.

    • to

      public 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. 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.
      Parameters:
      target - The target instance for the delegation.
      Returns:
      A method delegation that redirects method calls to a static method of the supplied type.

    • to

      public 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. 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.
      Parameters:
      target - The target instance for the delegation.
      methodGraphCompiler - The method graph compiler to use.
      Returns:
      A method delegation that redirects method calls to a static method of the supplied type.

    • to

      public 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. 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.
      Parameters:
      target - The target instance for the delegation.
      fieldName - The name of the field that is holding the target instance.
      Returns:
      A method delegation that redirects method calls to a static method of the supplied type.

    • to

      public 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. 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.
      Parameters:
      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.
      Returns:
      A method delegation that redirects method calls to a static method of the supplied type.

    • to

      public 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. 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.
      Parameters:
      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.
      Returns:
      A method delegation that redirects method calls to a static method of the supplied type.

    • to

      public 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. 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.
      Parameters:
      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.
      Returns:
      A method delegation that redirects method calls to a static method of the supplied type.

    • to

      public 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. 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.
      Parameters:
      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.
      Returns:
      A method delegation that redirects method calls to a static method of the supplied type.

    • to

      public 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. 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.
      Parameters:
      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.
      Returns:
      A method delegation that redirects method calls to a static method of the supplied type.

    • to

      public 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. 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.
      Parameters:
      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.
      Returns:
      A method delegation that redirects method calls to a static method of the supplied type.

    • to

      public 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. 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.
      Parameters:
      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.
      Returns:
      A method delegation that redirects method calls to a static method of the supplied type.

    • to

      public 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. 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.
      Parameters:
      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.
      Returns:
      A method delegation that redirects method calls to a static method of the supplied type.

    • to

      public 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. 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.
      Parameters:
      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.
      Returns:
      A method delegation that redirects method calls to a static method of the supplied type.

    • toConstructor

      public static MethodDelegation toConstructor(Class<?> type)
      Delegates any intercepted method to invoke a constructor of the supplied type. To be considered a valid delegation target, a constructor must be visible and accessible to the instrumented type. This is the case if the constructor's declaring type is either public or in the same package as the instrumented type and if the constructor is either public or non-private and in the same package as the instrumented type. Private constructors can only be used as a delegation target if the delegation is targeting the instrumented type.
      Parameters:
      type - The type to construct.
      Returns:
      A delegation that redirects method calls to a constructor of the supplied type.

    • toConstructor

      public static MethodDelegation toConstructor(TypeDescription typeDescription)
      Delegates any intercepted method to invoke a constructor of the supplied type. To be considered a valid delegation target, a constructor must be visible and accessible to the instrumented type. This is the case if the constructor's declaring type is either public or in the same package as the instrumented type and if the constructor is either public or non-private and in the same package as the instrumented type. Private constructors can only be used as a delegation target if the delegation is targeting the instrumented type.
      Parameters:
      typeDescription - The type to construct.
      Returns:
      A delegation that redirects method calls to a constructor of the supplied type.

    • toField

      public static MethodDelegation toField(String name)
      Delegates any intercepted method to invoke a non-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.
      Parameters:
      name - The field's name.
      Returns:
      A delegation that redirects invocations to a method of the specified field's instance.

    • toField

      public 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. 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.
      Parameters:
      name - The field's name.
      fieldLocatorFactory - The field locator factory to use.
      Returns:
      A delegation that redirects invocations to a method of the specified field's instance.

    • toField

      public 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. 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.
      Parameters:
      name - The field's name.
      methodGraphCompiler - The method graph compiler to use.
      Returns:
      A delegation that redirects invocations to a method of the specified field's instance.

    • toField

      public 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. 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.
      Parameters:
      name - The field's name.
      fieldLocatorFactory - The field locator factory to use.
      methodGraphCompiler - The method graph compiler to use.
      Returns:
      A delegation that redirects invocations to a method of the specified field's instance.

    • toMethodReturnOf

      public 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. 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.
      Parameters:
      name - The name of the method that returns the delegation target.
      Returns:
      A delegation that redirects invocations to the return value of a method that is declared by the instrumented type.

    • toMethodReturnOf

      public 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. 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.
      Parameters:
      name - The name of the method that returns the delegation target.
      methodGraphCompiler - The method graph compiler to use.
      Returns:
      A delegation that redirects invocations to the return value of a method that is declared by the instrumented type.

    • withDefaultConfiguration

      public 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.
      Returns:
      A method delegation configuration with pre-configuration.

    • withEmptyConfiguration

      public static MethodDelegation.WithCustomProperties withEmptyConfiguration()
      Creates a configuration builder for a method delegation that does not apply any pre-configured MethodDelegationBinder.AmbiguityResolvers or TargetMethodAnnotationDrivenBinder.ParameterBinders.
      Returns:
      A method delegation configuration without any pre-configuration.

    • withAssigner

      public Implementation.Composable withAssigner(Assigner assigner)
      Applies an assigner to the method delegation that is used for assigning method return and parameter types.
      Parameters:
      assigner - The assigner to apply.
      Returns:
      A method delegation implementation that makes use of the given designer.

    • andThen

      public Implementation andThen(Implementation implementation)
      Appends the supplied implementation to this implementation.
      Specified by:
      andThen in interface Implementation.Composable
      Parameters:
      implementation - The subsequent implementation.
      Returns:
      An implementation that combines this implementation with the provided one.

    • andThen

      public Implementation.Composable andThen(Implementation.Composable implementation)
      Appends the supplied composable implementation to this implementation.
      Specified by:
      andThen in interface Implementation.Composable
      Parameters:
      implementation - The subsequent composable implementation.
      Returns:
      A composable implementation that combines this implementation with the provided one.

    • prepare

      public InstrumentedType prepare(InstrumentedType instrumentedType)
      Prepares a given instrumented type.
      Specified by:
      prepare in interface InstrumentedType.Prepareable
      Parameters:
      instrumentedType - The instrumented type in its current form.
      Returns:
      The prepared instrumented type.

    • appender

      public ByteCodeAppender appender(Implementation.Target implementationTarget)
      Creates a byte code appender that determines the implementation of the instrumented type's methods.
      Specified by:
      appender in interface Implementation
      Parameters:
      implementationTarget - The target of the current implementation.
      Returns:
      A byte code appender for implementing methods delegated to this implementation. This byte code appender is also responsible for handling methods that were added by this implementation on the call to InstrumentedType.Prepareable.prepare(InstrumentedType).