net.bytebuddy.asm

Class Advice

java.lang.Object

net.bytebuddy.asm.Advice

All Implemented Interfaces:

AsmVisitorWrapper.ForDeclaredMethods.MethodVisitorWrapper

public class Advice
extends Object
implements AsmVisitorWrapper.ForDeclaredMethods.MethodVisitorWrapper

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 by Advice.OnMethodEnter and/or Advice.OnMethodExit and provided to an instance of this class.

A method that is annotated with Advice.OnMethodEnter can annotate its parameters with Advice.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 by Advice.This where the this reference of the instrumented is read when the parameter is accessed. This mechanism can also be used to assign a new value to the this reference of an instrumented method. If no annotation is used on a parameter, it is assigned the n-th parameter of the instrumented method for the n-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 the Advice.This reference respectively.

A method that is annotated with Advice.OnMethodExit can equally annotate its parameters with Advice.Argument and Advice.This. Additionally, it can annotate a parameter with Advice.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. to 0 for primitive return types and to null for reference return types. An exception can be read by annotating a parameter of type Throwable annotated with Advice.Thrown which is assigned the thrown Throwable or null 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 with Advice.OnMethodEnter exists and this method returns a value, this value can be accessed by a parameter annotated with Advice.Enter. This parameter must declare the same type as value that was returned by the method annotated with Advice.OnMethodEnter. If no such method exists or this method returns void, no such parameter must be declared. Any return type of a method that is annotated by Advice.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 by Advice.OnMethodExit method is not invoked. If the instrumented method throws an exception, the method that is annotated by Advice.OnMethodExit is only invoked if the Advice.OnMethodExit.onThrowable() property is set to true what is the default. If this property is set to false, the Advice.Thrown annotation must not be used on any parameter.

Byte Buddy does not assert the visibility of any types that are referenced within the advice methods. 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.

Important: Currently, it is required to make ASM recompute stack sizes and stack map frames by setting the ClassWriter.COMPUTE_FRAMES flag. This constraint will be relaxed in a future version.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	Advice.AdviceVisitor A method visitor that weaves the advise methods' byte codes.
static interface	Advice.Argument Indicates that the annotated parameter should be mapped to the parameter with index Advice.Argument.value() of the instrumented method.
protected static interface	Advice.Dispatcher A dispatcher for implementing advise.
static interface	Advice.Enter Indicates that the annotated parameter should be mapped to the value that is returned by the advise method that is annotated by Advice.OnMethodEnter.
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 inlined before the matched method is invoked.
static interface	Advice.Return Indicates that the annotated parameter should be mapped to the return value of the instrumented method.
static interface	Advice.This Indicates that the annotated parameter should be mapped to the this reference of the instrumented method.
static interface	Advice.Thrown Indicates that the annotated parameter should be mapped to the return value of the instrumented method.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Advice(Advice.Dispatcher.Resolved.ForMethodEnter methodEnter, Advice.Dispatcher.Resolved.ForMethodExit methodExit, byte[] binaryRepresentation) Creates a new advice.

Method Summary

Modifier and Type	Method and Description
boolean	equals(Object other)
int	hashCode()
static AsmVisitorWrapper.ForDeclaredMethods.MethodVisitorWrapper	to(Class<?> type) Implements advice where every matched method is advised by the given type's advisory methods.
static AsmVisitorWrapper.ForDeclaredMethods.MethodVisitorWrapper	to(Class<?> type, ClassFileLocator classFileLocator) Implements advice where every matched method is advised by the given type's advisory methods.
static AsmVisitorWrapper.ForDeclaredMethods.MethodVisitorWrapper	to(TypeDescription typeDescription, ClassFileLocator classFileLocator) Implements advice where every matched method is advised by the given type's advisory methods.
String	toString()
MethodVisitor	wrap(TypeDescription instrumentedType, MethodDescription.InDefinedShape methodDescription, MethodVisitor methodVisitor) Wraps a method visitor.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Advice

protected Advice(Advice.Dispatcher.Resolved.ForMethodEnter methodEnter,
                 Advice.Dispatcher.Resolved.ForMethodExit methodExit,
                 byte[] binaryRepresentation)

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.

binaryRepresentation - The binary representation of the class containing the advice methods.

Method Detail

to

public static AsmVisitorWrapper.ForDeclaredMethods.MethodVisitorWrapper to(Class<?> type)

Implements advice where every matched method is advised by the given type's advisory methods. The advises binary representation is accessed by querying the class loader of the supplied class for a class file.

Parameters:

type - The type declaring the advice.

Returns:

A method visitor wrapper representing the supplied advice.

to

public static AsmVisitorWrapper.ForDeclaredMethods.MethodVisitorWrapper to(Class<?> type,
                                                                           ClassFileLocator classFileLocator)

Implements advice where every matched method is advised by the given type's advisory methods.

Parameters:

type - 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 AsmVisitorWrapper.ForDeclaredMethods.MethodVisitorWrapper to(TypeDescription typeDescription,
                                                                           ClassFileLocator classFileLocator)

Implements advice where every matched method is advised by the given type's advisory methods.

Parameters:

typeDescription - 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.

wrap

public MethodVisitor wrap(TypeDescription instrumentedType,
                          MethodDescription.InDefinedShape methodDescription,
                          MethodVisitor methodVisitor)

Description copied from interface: AsmVisitorWrapper.ForDeclaredMethods.MethodVisitorWrapper

Wraps a method visitor.

Specified by:

wrap in interface AsmVisitorWrapper.ForDeclaredMethods.MethodVisitorWrapper

Parameters:

instrumentedType - The instrumented type.

methodDescription - The method that is currently being defined.

methodVisitor - The original field visitor that defines the given method.

Returns:

The wrapped method visitor.

equals

public boolean equals(Object other)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Overrides:

toString in class Object