Class MemberSubstitution

java.lang.Object
net.bytebuddy.asm.MemberSubstitution
All Implemented Interfaces:
AsmVisitorWrapper.ForDeclaredMethods.MethodVisitorWrapper
@Enhance public class MemberSubstitution extends Object implements AsmVisitorWrapper.ForDeclaredMethods.MethodVisitorWrapper

Substitutes field access, method invocations or constructor calls within a method's body.

Note: This substitution must not be used to match constructor calls to an instrumented class's super constructor invocation from within a constructor. Matching such constructors will result in an invalid stack and a verification error.

Note: This visitor will compute the required stack size on a best effort basis. For allocating an optimal stack size, ASM needs to be configured to compute the stack size.

Important: This component relies on using a TypePool for locating types within method bodies. Within a redefinition or a rebasement, this type pool normally resolved correctly by Byte Buddy. When subclassing a type, the type pool must be set explicitly, using DynamicType.Builder.make(TypePool) or any similar method. It is however not normally necessary to use this component when subclassing a type where methods are only defined explicitly.

  • Field Details

    • THIS_REFERENCE

      protected static final int THIS_REFERENCE
      The index of the this reference within a non-static method.
      See Also:

    • methodGraphCompiler

      private final MethodGraph.Compiler methodGraphCompiler
      The method graph compiler to use.

    • typePoolResolver

      private final MemberSubstitution.TypePoolResolver typePoolResolver
      The type pool resolver to use.

    • strict

      private final boolean strict
      true if the method processing should be strict where an exception is raised if a member cannot be found.

    • failIfNoMatch

      private final boolean failIfNoMatch
      true if the instrumentation should fail if applied to a method without match.

    • replacementFactory

      private final MemberSubstitution.Replacement.Factory replacementFactory
      The replacement factory to use.

  • Constructor Details

    • MemberSubstitution

      protected MemberSubstitution(boolean strict)
      Creates a default member substitution.
      Parameters:
      strict - true if the method processing should be strict where an exception is raised if a member cannot be found.

    • MemberSubstitution

      protected MemberSubstitution(MethodGraph.Compiler methodGraphCompiler, MemberSubstitution.TypePoolResolver typePoolResolver, boolean strict, boolean failIfNoMatch, MemberSubstitution.Replacement.Factory replacementFactory)
      Creates a new member substitution.
      Parameters:
      methodGraphCompiler - The method graph compiler to use.
      typePoolResolver - The type pool resolver to use.
      strict - true if the method processing should be strict where an exception is raised if a member cannot be found.
      failIfNoMatch - true if the instrumentation should fail if applied to a method without match.
      replacementFactory - The replacement factory to use.

  • Method Details

    • strict

      public static MemberSubstitution strict()
      Creates a member substitution that requires the resolution of all fields and methods that are referenced within a method body. Doing so, this component raises an exception if any member cannot be resolved what makes this component unusable when facing optional types.
      Returns:
      A strict member substitution.

    • relaxed

      public static MemberSubstitution relaxed()
      Creates a member substitution that skips any unresolvable fields or methods that are referenced within a method body. Using a relaxed member substitution, methods containing optional types are supported. In the process, it is however possible that misconfigurations of this component remain undiscovered.
      Returns:
      A relaxed member substitution.

    • element

      public MemberSubstitution.WithoutSpecification<MemberSubstitution.Target.ForMember> element(ElementMatcher<? super ByteCodeElement.Member> matcher)
      Substitutes any interaction with a field or method that matches the given matcher.
      Parameters:
      matcher - The matcher to determine what access to byte code elements to substitute.
      Returns:
      A specification that allows to determine how to substitute any interaction with byte code elements that match the supplied matcher.

    • field

      public MemberSubstitution.WithoutSpecification.ForMatchedField field(ElementMatcher<? super FieldDescription> matcher)
      Substitutes any field access that matches the given matcher.
      Parameters:
      matcher - The matcher to determine what fields to substitute.
      Returns:
      A specification that allows to determine how to substitute any field access that match the supplied matcher.

    • method

      public MemberSubstitution.WithoutSpecification.ForMatchedMethod method(ElementMatcher<? super MethodDescription> matcher)
      Substitutes any method invocation that matches the given matcher.
      Parameters:
      matcher - The matcher to determine what methods to substitute.
      Returns:
      A specification that allows to determine how to substitute any method invocations that match the supplied matcher.

    • constructor

      public MemberSubstitution.WithoutSpecification<MemberSubstitution.Target.ForMember> constructor(ElementMatcher<? super MethodDescription> matcher)
      Substitutes any constructor invocation that matches the given matcher.
      Parameters:
      matcher - The matcher to determine what constructors to substitute.
      Returns:
      A specification that allows to determine how to substitute any constructor invocations that match the supplied matcher.

    • invokable

      public MemberSubstitution.WithoutSpecification<MemberSubstitution.Target.ForMember> invokable(ElementMatcher<? super MethodDescription> matcher)
      Substitutes any method or constructor invocation that matches the given matcher.
      Parameters:
      matcher - The matcher to determine what method or constructors to substitute.
      Returns:
      A specification that allows to determine how to substitute any constructor invocations that match the supplied matcher.

    • lambdaExpression

      public MemberSubstitution.WithoutSpecification.ForMatchedDynamicInvocation lambdaExpression()
      Matches invokedynamic instructions which represents Java lambda expressions.
      Returns:
      A member substitution for Java lambda expressions.

    • dynamic

      public MemberSubstitution.WithoutSpecification.ForMatchedDynamicInvocation dynamic(ElementMatcher<? super JavaConstant.MethodHandle> matcher)
      Matches invokedynamic instructions that are dispatched for the supplied method handle.
      Parameters:
      matcher - A matcher for the invokedynamic's bootstrap method.
      Returns:
      A member substitution for invokedynamic instructions that are dispatched by any matched bootstrap method.

    • with

      public MemberSubstitution with(MethodGraph.Compiler methodGraphCompiler)
      Specifies the use of a specific method graph compiler for the resolution of virtual methods.
      Parameters:
      methodGraphCompiler - The method graph compiler to use.
      Returns:
      A new member substitution that is equal to this but uses the specified method graph compiler.

    • with

      public MemberSubstitution with(MemberSubstitution.TypePoolResolver typePoolResolver)
      Specifies a type pool resolver to be used for locating members.
      Parameters:
      typePoolResolver - The type pool resolver to use.
      Returns:
      A new instance of this member substitution that uses the supplied type pool resolver.

    • failIfNoMatch

      public MemberSubstitution failIfNoMatch(boolean failIfNoMatch)
      Specifies if this substitution should fail if applied on a method without a match.
      Parameters:
      failIfNoMatch - true if the instrumentation should fail if applied to a method without match.
      Returns:
      A new instance of this member substitution that fails if applied on a method without a match.

    • on

      public AsmVisitorWrapper.ForDeclaredMethods on(ElementMatcher<? super MethodDescription> matcher)
      Applies this member substitution to any method that matches the supplied matcher.
      Parameters:
      matcher - The matcher to determine this substitutions application.
      Returns:
      An ASM visitor wrapper that applies all specified substitutions for any matched method.

    • wrap

      public org.objectweb.asm.MethodVisitor wrap(TypeDescription instrumentedType, MethodDescription instrumentedMethod, org.objectweb.asm.MethodVisitor methodVisitor, Implementation.Context implementationContext, TypePool typePool, int writerFlags, int readerFlags)
      Wraps a method visitor.
      Specified by:
      wrap in interface AsmVisitorWrapper.ForDeclaredMethods.MethodVisitorWrapper
      Parameters:
      instrumentedType - The instrumented type.
      instrumentedMethod - The method that is currently being defined.
      methodVisitor - The original field visitor that defines the given method.
      implementationContext - The implementation context to use.
      typePool - The type pool to use.
      writerFlags - The ASM ClassWriter reader flags to consider.
      readerFlags - The ASM ClassReader reader flags to consider.
      Returns:
      The wrapped method visitor.