Class Advice
- java.lang.Object
-
- net.bytebuddy.asm.Advice
-
- All Implemented Interfaces:
AsmVisitorWrapper.ForDeclaredMethods.MethodVisitorWrapper
,InstrumentedType.Prepareable
,Implementation
@Enhance public class Advice extends java.lang.Object implements AsmVisitorWrapper.ForDeclaredMethods.MethodVisitorWrapper, Implementation
Advice wrappers copy the code of blueprint methods to be executed before and/or after a matched method. To achieve this, a
static
method of a class is annotated byAdvice.OnMethodEnter
and/orAdvice.OnMethodExit
and provided to an instance of this class.A method that is annotated with
Advice.OnMethodEnter
can annotate its parameters withAdvice.Argument
where field access to this parameter is substituted with access to the specified argument of the instrumented method. Alternatively, a parameter can be annotated byAdvice.This
where thethis
reference of the instrumented method is read when the parameter is accessed. This mechanism can also be used to assign a new value to thethis
reference of an instrumented method. If no annotation is used on a parameter, it is assigned then
-th parameter of the instrumented method for then
-th parameter of the advice method. All parameters must declare the exact same type as the parameters of the instrumented type or the method's declaring type for theAdvice.This
reference respectively if they are not marked as read-only. In the latter case, it suffices that a parameter type is a super type of the corresponding type of the instrumented method.A method that is annotated with
Advice.OnMethodExit
can equally annotate its parameters withAdvice.Argument
andAdvice.This
. Additionally, it can annotate a parameter withAdvice.Return
to receive the original method's return value. By reassigning the return value, it is possible to replace the returned value. If an instrumented method does not return a value, this annotation must not be used. If a method returns exceptionally, the parameter is set to its default value, i.e. to0
for primitive types and tonull
for reference types. The parameter's type must be equal to the instrumented method's return type if it is not set to read-only where it suffices to declare the parameter type to be of any super type to the instrumented method's return type. An exception can be read by annotating a parameter of typeThrowable
annotated withAdvice.Thrown
which is assigned the thrownThrowable
ornull
if a method returns normally. Doing so, it is possible to exchange a thrown exception with any checked or unchecked exception.Finally, if a method annotated withAdvice.OnMethodEnter
exists and this method returns a value, this value can be accessed by a parameter annotated withAdvice.Enter
. This parameter must declare the same type as type being returned by the method annotated withAdvice.OnMethodEnter
. If the parameter is marked to be read-only, it suffices that the annotated parameter is of a super type of the return type of the method annotated byAdvice.OnMethodEnter
. If no such method exists or this method returnsvoid
, no such parameter must be declared. Any return value of a method that is annotated byAdvice.OnMethodExit
is discarded.If any advice method throws an exception, the method is terminated prematurely. If the method annotated by
Advice.OnMethodEnter
throws an exception, the method annotated byAdvice.OnMethodExit
method is not invoked. If the instrumented method throws an exception, the method that is annotated byAdvice.OnMethodExit
is only invoked if theAdvice.OnMethodExit.onThrowable()
property is set totrue
what is the default. If this property is set tofalse
, theAdvice.Thrown
annotation must not be used on any parameter.Byte Buddy does not assert the visibility of any types that are referenced within an inlined advice method. It is the responsibility of the user of this class to assure that all types referenced within the advice methods are visible to the instrumented class. Failing to do so results in a
IllegalAccessError
at the instrumented class's runtime.Advice can be used either as a
AsmVisitorWrapper
where any declared methods of the currently instrumented type are enhanced without replacing an existing implementation. Alternatively, advice can function as anImplementation
where, by default, the original super or default method of the instrumented method is invoked. If this is not possible or undesired, the delegate implementation can be changed by specifying a wrapped implementation explicitly bywrap(Implementation)
.When using an advice class as a visitor wrapper, native or abstract methods which are silently skipped when advice matches such a method.
Important: Since Java 6, class files contain stack map frames embedded into a method's byte code. When advice methods are compiled with a class file version less then Java 6 but are used for a class file that was compiled to Java 6 or newer, these stack map frames must be computed by ASM by using the
ClassWriter.COMPUTE_FRAMES
option. If the advice methods do not contain any branching instructions, this is not required. No action is required if the advice methods are at least compiled with Java 6 but are used on classes older than Java 6. This limitation only applies to advice methods that are inlined. Also, it is the responsibility of this class's user to assure that the advice method does not contain byte code constructs that are not supported by the class containing the instrumented method. In particular, pre Java-5 try-finally blocks cannot be inlined into classes with newer byte code levels as the jsr instruction was deprecated. Also, classes prior to Java 7 do not support the invokedynamic command which must not be contained by an advice method if the instrumented method targets an older class file format version.Note: For the purpose of inlining, Java 5 and Java 6 byte code can be seen as the best candidate for advice methods. These versions do no longer allow subroutines, neither do they already allow invokedynamic instructions or method handles. This way, Java 5 and Java 6 byte code is compatible to both older and newer versions. One exception for backwards-incompatible byte code is the possibility to load type references from the constant pool onto the operand stack. These instructions can however easily be transformed for classes compiled to Java 4 and older by registering a
TypeConstantAdjustment
before the advice visitor.Note: It is not possible to trigger break points in inlined advice methods as the debugging information of the inlined advice is not preserved. It is not possible in Java to reference more than one source file per class what makes translating such debugging information impossible. It is however possible to set break points in advice methods when invoking the original advice target. This allows debugging of advice code within unit tests that invoke the advice method without instrumentation. As a consequence of not transferring debugging information, the names of the parameters of an advice method do not matter when inlining, neither does any meta information on the advice method's body such as annotations or parameter modifiers.
Note: The behavior of this component is undefined if it is supplied with invalid byte code what might result in runtime exceptions.
Note: When using advice from a Java agent with an
AgentBuilder
, it often makes sense to not include any library-specific code in the agent's jar file. For being able to locate the advice code in the context of the library dependencies, Byte Buddy offers anAgentBuilder.Transformer.ForAdvice
implementation that allows registering the agent's class file locators for assembly of the advice class's description at runtime and with respect to the specific user dependencies.- See Also:
Advice.OnMethodEnter
,Advice.OnMethodExit
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description protected static class
Advice.AdviceVisitor
A method visitor that weaves the advice methods' byte codes.static interface
Advice.AllArguments
Assigns an array containing all arguments of the instrumented method to the annotated parameter.protected static class
Advice.Appender
A byte code appender for implementingAdvice
.static interface
Advice.Argument
Indicates that the annotated parameter should be mapped to the parameter with indexAdvice.Argument.value()
of the instrumented method.static interface
Advice.ArgumentHandler
An argument handler is responsible for resolving offsets of the local variable array in the context of the applied instrumentation.protected static interface
Advice.Delegator
Materializes an advice invocation within a delegation.protected static interface
Advice.Dispatcher
A dispatcher for implementing advice.static interface
Advice.Enter
Indicates that the annotated parameter should be mapped to the value that is returned by the advice method that is annotated byAdvice.OnMethodEnter
.static interface
Advice.ExceptionHandler
An exception handler is responsible for providing byte code for handling an exception thrown from a suppressing advice method.static interface
Advice.Exit
Indicates that the annotated parameter should be mapped to the value that is returned by the advice method that is annotated byAdvice.OnMethodExit
.static interface
Advice.FieldValue
Indicates that the annotated parameter should be mapped to a field in the scope of the instrumented method.static interface
Advice.Local
Declares the annotated parameter as a local variable that is created by Byte Buddy for the instrumented method.protected static interface
Advice.MethodSizeHandler
A handler for computing the instrumented method's size.private static class
Advice.NoExceptionHandler
A marker class that indicates that an advice method does not suppress anyThrowable
.static interface
Advice.OffsetMapping
Represents an offset mapping for an advice method to an alternative offset.static class
Advice.OnDefaultValue
A marker type to be used as an argument forAdvice.OnMethodEnter.skipOn()
.static interface
Advice.OnMethodEnter
Indicates that this method should be inlined before the matched method is invoked.static interface
Advice.OnMethodExit
Indicates that this method should be executed before exiting the instrumented method.static class
Advice.OnNonDefaultValue
A marker type to be used as an argument forAdvice.OnMethodEnter.skipOn()
.static interface
Advice.Origin
Indicates that the annotated parameter should be mapped to a string representation of the instrumented method, a constant representing theClass
declaring the adviced method or aMethod
,Constructor
orjava.lang.reflect.Executable
representing this method.static interface
Advice.PostProcessor
A post processor for advice methods that is invoked after advice is executed.static interface
Advice.Return
Indicates that the annotated parameter should be mapped to the return value of the instrumented method.protected static interface
Advice.StackMapFrameHandler
A handler for computing and translating stack map frames.static interface
Advice.StubValue
Indicates that the annotated parameter should always return a default a boxed version of the instrumented methods return value (i.e.static interface
Advice.This
Indicates that the annotated parameter should be mapped to thethis
reference of the instrumented method.static interface
Advice.Thrown
Indicates that the annotated parameter should be mapped to theThrowable
thrown by the instrumented method or tonull
if the method returned regularly.static interface
Advice.Unused
Indicates that the annotated parameter should always return a default value (i.e.static class
Advice.WithCustomMapping
A builder step for creating anAdvice
that uses custom mappings of annotations to constant pool values.-
Nested classes/interfaces inherited from interface net.bytebuddy.implementation.Implementation
Implementation.Composable, Implementation.Compound, Implementation.Context, Implementation.Simple, Implementation.SpecialMethodInvocation, Implementation.Target
-
-
Field Summary
Fields Modifier and Type Field Description private Assigner
assigner
The assigner to use.private static MethodDescription.InDefinedShape
BACKUP_ARGUMENTS
A reference to theAdvice.OnMethodExit.backupArguments()
method.private Implementation
delegate
The delegate implementation to apply if this advice is used as an instrumentation.private Advice.ExceptionHandler
exceptionHandler
The exception handler to apply.private static MethodDescription.InDefinedShape
INLINE_ENTER
A reference to theAdvice.OnMethodEnter.inline()
method.private static MethodDescription.InDefinedShape
INLINE_EXIT
A reference to theAdvice.OnMethodExit.inline()
method.private Advice.Dispatcher.Resolved.ForMethodEnter
methodEnter
The dispatcher for instrumenting the instrumented method upon entering.private Advice.Dispatcher.Resolved.ForMethodExit
methodExit
The dispatcher for instrumenting the instrumented method upon exiting.private static MethodDescription.InDefinedShape
ON_THROWABLE
A reference to theAdvice.OnMethodExit.onThrowable()
method.private static MethodDescription.InDefinedShape
PREPEND_LINE_NUMBER
A reference to theAdvice.OnMethodEnter.prependLineNumber()
method.private static MethodDescription.InDefinedShape
REPEAT_ON
A reference to theAdvice.OnMethodExit.repeatOn()
method.private static MethodDescription.InDefinedShape
SKIP_ON
A reference to theAdvice.OnMethodEnter.skipOn()
method.private static MethodDescription.InDefinedShape
SUPPRESS_ENTER
A reference to theAdvice.OnMethodEnter.suppress()
method.private static MethodDescription.InDefinedShape
SUPPRESS_EXIT
A reference to theAdvice.OnMethodExit.suppress()
method.private static org.objectweb.asm.ClassReader
UNDEFINED
Indicates that no class reader is available to an advice method.
-
Constructor Summary
Constructors Modifier Constructor Description protected
Advice(Advice.Dispatcher.Resolved.ForMethodEnter methodEnter, Advice.Dispatcher.Resolved.ForMethodExit methodExit)
Creates a new advice.private
Advice(Advice.Dispatcher.Resolved.ForMethodEnter methodEnter, Advice.Dispatcher.Resolved.ForMethodExit methodExit, Assigner assigner, Advice.ExceptionHandler exceptionHandler, Implementation delegate)
Creates a new advice.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description ByteCodeAppender
appender(Implementation.Target implementationTarget)
Creates a byte code appender that determines the implementation of the instrumented type's methods.protected org.objectweb.asm.MethodVisitor
doWrap(TypeDescription instrumentedType, MethodDescription instrumentedMethod, org.objectweb.asm.MethodVisitor methodVisitor, Implementation.Context implementationContext, int writerFlags, int readerFlags)
Wraps the method visitor to implement this advice.private static Advice.Dispatcher.Unresolved
locate(java.lang.Class<? extends java.lang.annotation.Annotation> type, MethodDescription.InDefinedShape property, Advice.Dispatcher.Unresolved dispatcher, MethodDescription.InDefinedShape methodDescription, Advice.Delegator delegator)
Locates a dispatcher for the method if available.AsmVisitorWrapper.ForDeclaredMethods
on(ElementMatcher<? super MethodDescription> matcher)
Returns an ASM visitor wrapper that matches the given matcher and applies this advice to the matched methods.InstrumentedType
prepare(InstrumentedType instrumentedType)
Prepares a given instrumented type.static Advice
to(java.lang.Class<?> advice)
Implements advice where every matched method is advised by the given type's advisory methods.static Advice
to(java.lang.Class<?> enterAdvice, java.lang.Class<?> exitAdvice)
Implements advice where every matched method is advised by the given type's advisory methods.static Advice
to(java.lang.Class<?> enterAdvice, java.lang.Class<?> exitAdvice, ClassFileLocator classFileLocator)
Implements advice where every matched method is advised by the given type's advisory methods.static Advice
to(java.lang.Class<?> advice, ClassFileLocator classFileLocator)
Implements advice where every matched method is advised by the given type's advisory methods.static Advice
to(TypeDescription advice)
Implements advice where every matched method is advised by the given type's advisory methods.protected static Advice
to(TypeDescription advice, Advice.PostProcessor.Factory postProcessorFactory, ClassFileLocator classFileLocator, java.util.List<? extends Advice.OffsetMapping.Factory<?>> userFactories, Advice.Delegator delegator)
Creates a new advice.static Advice
to(TypeDescription enterAdvice, TypeDescription exitAdvice)
Implements advice where every matched method is advised by the given type's advisory methods.protected static Advice
to(TypeDescription enterAdvice, TypeDescription exitAdvice, Advice.PostProcessor.Factory postProcessorFactory, ClassFileLocator classFileLocator, java.util.List<? extends Advice.OffsetMapping.Factory<?>> userFactories, Advice.Delegator delegator)
Creates a new advice.static Advice
to(TypeDescription enterAdvice, TypeDescription exitAdvice, ClassFileLocator classFileLocator)
Implements advice where every matched method is advised by the given type's advisory methods.static Advice
to(TypeDescription advice, ClassFileLocator classFileLocator)
Implements advice where every matched method is advised by the given type's advisory methods.Advice
withAssigner(Assigner assigner)
Configures this advice to use the specified assigner.static Advice.WithCustomMapping
withCustomMapping()
Allows for the configuration of custom annotations that are then bound to a dynamically computed, constant value.Advice
withExceptionHandler(Advice.ExceptionHandler exceptionHandler)
Configures this advice to execute the given exception handler upon a suppressed exception.Advice
withExceptionHandler(StackManipulation exceptionHandler)
Configures this advice to execute the given stack manipulation upon a suppressed exception.Advice
withExceptionPrinting()
Configures this advice to callThrowable.printStackTrace()
upon a suppressed exception.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.Implementation
wrap(Implementation implementation)
Wraps the supplied implementation to have this advice applied around it.
-
-
-
Field Detail
-
UNDEFINED
private static final org.objectweb.asm.ClassReader UNDEFINED
Indicates that no class reader is available to an advice method.
-
SKIP_ON
private static final MethodDescription.InDefinedShape SKIP_ON
A reference to theAdvice.OnMethodEnter.skipOn()
method.
-
PREPEND_LINE_NUMBER
private static final MethodDescription.InDefinedShape PREPEND_LINE_NUMBER
A reference to theAdvice.OnMethodEnter.prependLineNumber()
method.
-
INLINE_ENTER
private static final MethodDescription.InDefinedShape INLINE_ENTER
A reference to theAdvice.OnMethodEnter.inline()
method.
-
SUPPRESS_ENTER
private static final MethodDescription.InDefinedShape SUPPRESS_ENTER
A reference to theAdvice.OnMethodEnter.suppress()
method.
-
REPEAT_ON
private static final MethodDescription.InDefinedShape REPEAT_ON
A reference to theAdvice.OnMethodExit.repeatOn()
method.
-
ON_THROWABLE
private static final MethodDescription.InDefinedShape ON_THROWABLE
A reference to theAdvice.OnMethodExit.onThrowable()
method.
-
BACKUP_ARGUMENTS
private static final MethodDescription.InDefinedShape BACKUP_ARGUMENTS
A reference to theAdvice.OnMethodExit.backupArguments()
method.
-
INLINE_EXIT
private static final MethodDescription.InDefinedShape INLINE_EXIT
A reference to theAdvice.OnMethodExit.inline()
method.
-
SUPPRESS_EXIT
private static final MethodDescription.InDefinedShape SUPPRESS_EXIT
A reference to theAdvice.OnMethodExit.suppress()
method.
-
methodEnter
private final Advice.Dispatcher.Resolved.ForMethodEnter methodEnter
The dispatcher for instrumenting the instrumented method upon entering.
-
methodExit
private final Advice.Dispatcher.Resolved.ForMethodExit methodExit
The dispatcher for instrumenting the instrumented method upon exiting.
-
assigner
private final Assigner assigner
The assigner to use.
-
exceptionHandler
private final Advice.ExceptionHandler exceptionHandler
The exception handler to apply.
-
delegate
private final Implementation delegate
The delegate implementation to apply if this advice is used as an instrumentation.
-
-
Constructor Detail
-
Advice
protected Advice(Advice.Dispatcher.Resolved.ForMethodEnter methodEnter, Advice.Dispatcher.Resolved.ForMethodExit methodExit)
Creates a new advice.- Parameters:
methodEnter
- The dispatcher for instrumenting the instrumented method upon entering.methodExit
- The dispatcher for instrumenting the instrumented method upon exiting.
-
Advice
private Advice(Advice.Dispatcher.Resolved.ForMethodEnter methodEnter, Advice.Dispatcher.Resolved.ForMethodExit methodExit, Assigner assigner, Advice.ExceptionHandler exceptionHandler, Implementation delegate)
Creates a new advice.- Parameters:
methodEnter
- The dispatcher for instrumenting the instrumented method upon entering.methodExit
- The dispatcher for instrumenting the instrumented method upon exiting.assigner
- The assigner to use.exceptionHandler
- The exception handler to apply.delegate
- The delegate implementation to apply if this advice is used as an instrumentation.
-
-
Method Detail
-
to
public static Advice to(java.lang.Class<?> advice)
Implements advice where every matched method is advised by the given type's advisory methods. The advices binary representation is accessed by querying the class loader of the supplied class for a class file.- Parameters:
advice
- The type declaring the advice.- Returns:
- A method visitor wrapper representing the supplied advice.
-
to
public static Advice to(java.lang.Class<?> advice, ClassFileLocator classFileLocator)
Implements advice where every matched method is advised by the given type's advisory methods.- Parameters:
advice
- The type declaring the advice.classFileLocator
- The class file locator for locating the advisory class's class file.- Returns:
- A method visitor wrapper representing the supplied advice.
-
to
public static Advice to(TypeDescription advice)
Implements advice where every matched method is advised by the given type's advisory methods. Using this method, a non-operational class file locator is specified for the advice target. This implies that only advice targets with the inline target set tofalse
are resolvable by the returned instance.- Parameters:
advice
- The type declaring the advice.- Returns:
- A method visitor wrapper representing the supplied advice.
-
to
public static Advice to(TypeDescription advice, ClassFileLocator classFileLocator)
Implements advice where every matched method is advised by the given type's advisory methods.- Parameters:
advice
- A description of the type declaring the advice.classFileLocator
- The class file locator for locating the advisory class's class file.- Returns:
- A method visitor wrapper representing the supplied advice.
-
to
protected static Advice to(TypeDescription advice, Advice.PostProcessor.Factory postProcessorFactory, ClassFileLocator classFileLocator, java.util.List<? extends Advice.OffsetMapping.Factory<?>> userFactories, Advice.Delegator delegator)
Creates a new advice.- Parameters:
advice
- A description of the type declaring the advice.postProcessorFactory
- The post processor factory to use.classFileLocator
- The class file locator for locating the advisory class's class file.userFactories
- A list of custom factories for user generated offset mappings.delegator
- The delegator to use.- Returns:
- A method visitor wrapper representing the supplied advice.
-
to
public static Advice to(java.lang.Class<?> enterAdvice, java.lang.Class<?> exitAdvice)
Implements advice where every matched method is advised by the given type's advisory methods. The advices binary representation is accessed by querying the class loader of the supplied class for a class file.- Parameters:
enterAdvice
- The type declaring the enter advice.exitAdvice
- The type declaring the exit advice.- Returns:
- A method visitor wrapper representing the supplied advice.
-
to
public static Advice to(java.lang.Class<?> enterAdvice, java.lang.Class<?> exitAdvice, ClassFileLocator classFileLocator)
Implements advice where every matched method is advised by the given type's advisory methods.- Parameters:
enterAdvice
- The type declaring the enter advice.exitAdvice
- The type declaring the exit advice.classFileLocator
- The class file locator for locating the advisory class's class file.- Returns:
- A method visitor wrapper representing the supplied advice.
-
to
public static Advice to(TypeDescription enterAdvice, TypeDescription exitAdvice)
Implements advice where every matched method is advised by the given type's advisory methods. Using this method, a non-operational class file locator is specified for the advice target. This implies that only advice targets with the inline target set tofalse
are resolvable by the returned instance.- Parameters:
enterAdvice
- The type declaring the enter advice.exitAdvice
- The type declaring the exit advice.- Returns:
- A method visitor wrapper representing the supplied advice.
-
to
public static Advice to(TypeDescription enterAdvice, TypeDescription exitAdvice, ClassFileLocator classFileLocator)
Implements advice where every matched method is advised by the given type's advisory methods.- Parameters:
enterAdvice
- The type declaring the enter advice.exitAdvice
- The type declaring the exit advice.classFileLocator
- The class file locator for locating the advisory class's class file.- Returns:
- A method visitor wrapper representing the supplied advice.
-
to
protected static Advice to(TypeDescription enterAdvice, TypeDescription exitAdvice, Advice.PostProcessor.Factory postProcessorFactory, ClassFileLocator classFileLocator, java.util.List<? extends Advice.OffsetMapping.Factory<?>> userFactories, Advice.Delegator delegator)
Creates a new advice.- Parameters:
enterAdvice
- The type declaring the enter advice.exitAdvice
- The type declaring the exit advice.postProcessorFactory
- The post processor factory to use.classFileLocator
- The class file locator for locating the advisory class's class file.userFactories
- A list of custom factories for user generated offset mappings.delegator
- The delegator to use.- Returns:
- A method visitor wrapper representing the supplied advice.
-
locate
private static Advice.Dispatcher.Unresolved locate(java.lang.Class<? extends java.lang.annotation.Annotation> type, MethodDescription.InDefinedShape property, Advice.Dispatcher.Unresolved dispatcher, MethodDescription.InDefinedShape methodDescription, Advice.Delegator delegator)
Locates a dispatcher for the method if available.- Parameters:
type
- The annotation type that indicates a given form of advice that is currently resolved.property
- An annotation property that indicates if the advice method should be inlined.dispatcher
- Any previous dispatcher that was discovered ornull
if no such dispatcher was yet found.methodDescription
- The method description that is considered as an advice method.delegator
- The delegator to use.- Returns:
- A resolved dispatcher or
null
if no dispatcher was resolved.
-
withCustomMapping
public static Advice.WithCustomMapping withCustomMapping()
Allows for the configuration of custom annotations that are then bound to a dynamically computed, constant value.- Returns:
- A builder for an
Advice
instrumentation with custom values. - See Also:
Advice.OffsetMapping.Factory
-
on
public AsmVisitorWrapper.ForDeclaredMethods on(ElementMatcher<? super MethodDescription> matcher)
Returns an ASM visitor wrapper that matches the given matcher and applies this advice to the matched methods.- Parameters:
matcher
- The matcher identifying methods to apply the advice to.- Returns:
- A suitable ASM visitor wrapper with the compute frames option enabled.
-
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.
-
doWrap
protected org.objectweb.asm.MethodVisitor doWrap(TypeDescription instrumentedType, MethodDescription instrumentedMethod, org.objectweb.asm.MethodVisitor methodVisitor, Implementation.Context implementationContext, int writerFlags, int readerFlags)
Wraps the method visitor to implement this advice.- Parameters:
instrumentedType
- The instrumented type.instrumentedMethod
- The instrumented method.methodVisitor
- The method visitor to write to.implementationContext
- The implementation context to use.writerFlags
- The ASM writer flags to use.readerFlags
- The ASM reader flags to use.- Returns:
- A method visitor that applies this advice.
-
prepare
public InstrumentedType prepare(InstrumentedType instrumentedType)
Prepares a given instrumented type.- Specified by:
prepare
in interfaceInstrumentedType.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 interfaceImplementation
- 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)
.
-
withAssigner
public Advice withAssigner(Assigner assigner)
Configures this advice to use the specified assigner. Any previous or default assigner is replaced.- Parameters:
assigner
- The assigner to use,- Returns:
- A version of this advice that uses the specified assigner.
-
withExceptionPrinting
public Advice withExceptionPrinting()
Configures this advice to callThrowable.printStackTrace()
upon a suppressed exception.- Returns:
- A version of this advice that prints any suppressed exception.
-
withExceptionHandler
public Advice withExceptionHandler(StackManipulation exceptionHandler)
Configures this advice to execute the given stack manipulation upon a suppressed exception. The stack manipulation is executed with aThrowable
instance on the operand stack. The stack must be empty upon completing the exception handler.- Parameters:
exceptionHandler
- The exception handler to apply.- Returns:
- A version of this advice that applies the supplied exception handler.
-
withExceptionHandler
public Advice withExceptionHandler(Advice.ExceptionHandler exceptionHandler)
Configures this advice to execute the given exception handler upon a suppressed exception. The stack manipulation is executed with aThrowable
instance on the operand stack. The stack must be empty upon completing the exception handler.- Parameters:
exceptionHandler
- The exception handler to apply.- Returns:
- A version of this advice that applies the supplied exception handler.
-
wrap
public Implementation wrap(Implementation implementation)
Wraps the supplied implementation to have this advice applied around it.- Parameters:
implementation
- The implementation to wrap.- Returns:
- An implementation that applies the supplied implementation and wraps it with this advice.
-
-