Class MemberSubstitution
- java.lang.Object
-
- net.bytebuddy.asm.MemberSubstitution
-
- All Implemented Interfaces:
AsmVisitorWrapper.ForDeclaredMethods.MethodVisitorWrapper
@Enhance public class MemberSubstitution extends java.lang.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, usingDynamicType.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.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static interface
MemberSubstitution.AllArguments
Assigns an array containing all arguments of the targeted element to the annotated parameter.static interface
MemberSubstitution.Argument
Indicates that the annotated parameter should be mapped to the parameter with indexMemberSubstitution.Argument.value()
.static interface
MemberSubstitution.Current
Indicates that the annotated parameter should be assigned the value of the result that was yielded by the previous chain expression.static interface
MemberSubstitution.DynamicConstant
Indicates that the annotated parameter should load a dynamic constant using the specificied bootstrap method.static interface
MemberSubstitution.FieldGetterHandle
Indicates that the annotated parameter should be mapped to ajava.lang.invoke.MethodHandle
representing a field getter.static interface
MemberSubstitution.FieldSetterHandle
Indicates that the annotated parameter should be mapped to ajava.lang.invoke.MethodHandle
representing a field setter.static interface
MemberSubstitution.FieldValue
Indicates that the annotated parameter should be mapped to a field in the scope of the instrumented type.static interface
MemberSubstitution.Handle
Indicates that the annotated parameter should load ajava.lang.invoke.MethodHandle
that represents an invocation of the specified expression.protected static class
MemberSubstitution.LambdaMetaFactoryMatcher
A matcher for method handles of thejava.lang.invoke.LambdaMetafactory
.static interface
MemberSubstitution.Origin
Indicates that the annotated parameter should be mapped to a representation of the substituted element or instrumented method.protected static interface
MemberSubstitution.Replacement
A replacement combines aMemberSubstitution.Substitution
and a way of choosing if this substitution should be applied for a discovered member.static interface
MemberSubstitution.SelfCallHandle
Indicates that the annotated parameter should load ajava.lang.invoke.MethodHandle
that represents an invocation of the substituted expression or instrumented method.static class
MemberSubstitution.Source
Identifies the source of an instruction that might describe a value of the substituted element or the instrumented method.static interface
MemberSubstitution.StubValue
Indicates that the annotated parameter should always return a boxed version of the instrumented method's return value (i.e.protected static class
MemberSubstitution.SubstitutingMethodVisitor
A method visitor that applies a substitution for matched methods.static interface
MemberSubstitution.Substitution
A substitution replaces or enhances an interaction with a field or method within an instrumented method.static interface
MemberSubstitution.Target
Representation of a substitution target within a method body.static interface
MemberSubstitution.This
Indicates that the annotated parameter should be mapped to thethis
reference of the substituted field, method, constructor or of the instrumented method.static interface
MemberSubstitution.TypePoolResolver
A type pool resolver is responsible for resolving aTypePool
for locating substituted members.static interface
MemberSubstitution.Unused
Indicates that the annotated parameter should always return a default value (i.e.static class
MemberSubstitution.WithoutSpecification
A member substitution that lacks a specification for how to substitute the matched members references within a method body.
-
Field Summary
Fields Modifier and Type Field Description private boolean
failIfNoMatch
true
if the instrumentation should fail if applied to a method without match.private MethodGraph.Compiler
methodGraphCompiler
The method graph compiler to use.private MemberSubstitution.Replacement.Factory
replacementFactory
The replacement factory to use.private boolean
strict
true
if the method processing should be strict where an exception is raised if a member cannot be found.protected static int
THIS_REFERENCE
The index of the this reference within a non-static method.private MemberSubstitution.TypePoolResolver
typePoolResolver
The type pool resolver to use.
-
Constructor Summary
Constructors Modifier Constructor Description protected
MemberSubstitution(boolean strict)
Creates a default member substitution.protected
MemberSubstitution(MethodGraph.Compiler methodGraphCompiler, MemberSubstitution.TypePoolResolver typePoolResolver, boolean strict, boolean failIfNoMatch, MemberSubstitution.Replacement.Factory replacementFactory)
Creates a new member substitution.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description MemberSubstitution.WithoutSpecification
constructor(ElementMatcher<? super MethodDescription> matcher)
Substitutes any constructor invocation that matches the given matcher.MemberSubstitution.WithoutSpecification.ForMatchedDynamicInvocation
dynamic(ElementMatcher<? super JavaConstant.MethodHandle> matcher)
Matches invokedynamic instructions that are dispatched for the supplied method handle.MemberSubstitution.WithoutSpecification
element(ElementMatcher<? super ByteCodeElement.Member> matcher)
Substitutes any interaction with a field or method that matches the given matcher.MemberSubstitution
failIfNoMatch(boolean failIfNoMatch)
Specifies if this substitution should fail if applied on a method without a match.MemberSubstitution.WithoutSpecification.ForMatchedField
field(ElementMatcher<? super FieldDescription> matcher)
Substitutes any field access that matches the given matcher.MemberSubstitution.WithoutSpecification
invokable(ElementMatcher<? super MethodDescription> matcher)
Substitutes any method or constructor invocation that matches the given matcher.MemberSubstitution.WithoutSpecification.ForMatchedDynamicInvocation
lambdaExpression()
Matches invokedynamic instructions which represents Java lambda expressions.MemberSubstitution.WithoutSpecification.ForMatchedMethod
method(ElementMatcher<? super MethodDescription> matcher)
Substitutes any method invocation that matches the given matcher.AsmVisitorWrapper.ForDeclaredMethods
on(ElementMatcher<? super MethodDescription> matcher)
Applies this member substitution to any method that matches the supplied matcher.static MemberSubstitution
relaxed()
Creates a member substitution that skips any unresolvable fields or methods that are referenced within a method body.static MemberSubstitution
strict()
Creates a member substitution that requires the resolution of all fields and methods that are referenced within a method body.MemberSubstitution
with(MemberSubstitution.TypePoolResolver typePoolResolver)
Specifies a type pool resolver to be used for locating members.MemberSubstitution
with(MethodGraph.Compiler methodGraphCompiler)
Specifies the use of a specific method graph compiler for the resolution of virtual methods.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.
-
-
-
Field Detail
-
THIS_REFERENCE
protected static final int THIS_REFERENCE
The index of the this reference within a non-static method.- See Also:
- Constant Field Values
-
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 Detail
-
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 Detail
-
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 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 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 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 interfaceAsmVisitorWrapper.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 ASMClassWriter
reader flags to consider.readerFlags
- The ASMClassReader
reader flags to consider.- Returns:
- The wrapped method visitor.
-
-