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 method 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 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 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 types and to null
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 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 type being returned by the method annotated with Advice.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 by
Advice.OnMethodEnter
. If no such method exists or this method returns void
, no such parameter must be declared. Any return value
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 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 cannot be applied to 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 transformerd 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 conequence 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.
Modifier and Type | Class and Description |
---|---|
protected static class |
Advice.AdviceVisitor
A method visitor that weaves the advice 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. |
static interface |
Advice.BoxedArguments
Indicates that the annotated parameter should be mapped to an array containing a (boxed) version of all arguments of the
method being instrumented.
|
static interface |
Advice.BoxedReturn
Indicates that the annotated parameter should be mapped to a the return value where primitive types are boxed.
|
protected static interface |
Advice.Dispatcher
A dispatcher for implementing advice.
|
static interface |
Advice.DynamicValue<T extends Annotation>
A dynamic value allows to bind parameters of an
Advice method to a custom, constant value. |
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
by
Advice.OnMethodEnter . |
static interface |
Advice.FieldValue
Indicates that the annotated parameter should be mapped to a field in the scope of the instrumented method.
|
protected static interface |
Advice.MethodSizeHandler
A handler for computing the instrumented method's size.
|
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 interface |
Advice.Origin
Indicates that the annotated parameter should be mapped to a string representation of the instrumented method or
to a constant representing the
Class declaring the method. |
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 value (i.e.
|
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.
|
static class |
Advice.WithCustomMapping
A builder step for creating an
Advice that uses custom mappings of annotations to constant pool values. |
Modifier | Constructor and Description |
---|---|
protected |
Advice(Advice.Dispatcher.Resolved.ForMethodEnter methodEnter,
Advice.Dispatcher.Resolved.ForMethodExit methodExit)
Creates a new advice.
|
Modifier and Type | Method and Description |
---|---|
boolean |
equals(Object other) |
int |
hashCode() |
AsmVisitorWrapper.ForDeclaredMethods |
on(ElementMatcher<? super MethodDescription.InDefinedShape> matcher)
Returns an ASM visitor wrapper that matches the given matcher and applies this advice to the matched methods.
|
static Advice |
to(Class<?> advice)
Implements advice where every matched method is advised by the given type's advisory methods.
|
static Advice |
to(Class<?> enterAdvice,
Class<?> exitAdvice)
Implements advice where every matched method is advised by the given type's advisory methods.
|
static Advice |
to(Class<?> enterAdvice,
Class<?> exitAdvice,
ClassFileLocator classFileLocator)
Implements advice where every matched method is advised by the given type's advisory methods.
|
static Advice |
to(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.
|
static Advice |
to(TypeDescription advice,
ClassFileLocator classFileLocator)
Implements advice where every matched method is advised by the given type's advisory methods.
|
protected static Advice |
to(TypeDescription advice,
ClassFileLocator classFileLocator,
List<? extends Advice.Dispatcher.OffsetMapping.Factory> userFactories)
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.
|
static Advice |
to(TypeDescription enterAdvice,
TypeDescription exitAdvice,
ClassFileLocator classFileLocator)
Implements advice where every matched method is advised by the given type's advisory methods.
|
protected static Advice |
to(TypeDescription enterAdvice,
TypeDescription exitAdvice,
ClassFileLocator classFileLocator,
List<? extends Advice.Dispatcher.OffsetMapping.Factory> userFactories)
Creates a new advice.
|
String |
toString() |
static Advice.WithCustomMapping |
withCustomMapping()
Allows for the configuration of custom annotations that are then bound to a dynamically computed, constant value.
|
MethodVisitor |
wrap(TypeDescription instrumentedType,
MethodDescription.InDefinedShape methodDescription,
MethodVisitor methodVisitor,
ClassFileVersion classFileVersion,
int writerFlags,
int readerFlags)
Wraps a method visitor.
|
protected Advice(Advice.Dispatcher.Resolved.ForMethodEnter methodEnter, Advice.Dispatcher.Resolved.ForMethodExit methodExit)
methodEnter
- The dispatcher for instrumenting the instrumented method upon entering.methodExit
- The dispatcher for instrumenting the instrumented method upon exiting.public static Advice to(Class<?> advice)
advice
- The type declaring the advice.public static Advice to(Class<?> advice, ClassFileLocator classFileLocator)
advice
- The type declaring the advice.classFileLocator
- The class file locator for locating the advisory class's class file.public static Advice to(TypeDescription advice)
false
are resolvable by the returned instance.advice
- The type declaring the advice.public static Advice to(TypeDescription advice, ClassFileLocator classFileLocator)
advice
- A description of the type declaring the advice.classFileLocator
- The class file locator for locating the advisory class's class file.protected static Advice to(TypeDescription advice, ClassFileLocator classFileLocator, List<? extends Advice.Dispatcher.OffsetMapping.Factory> userFactories)
advice
- A description of the type declaring the advice.classFileLocator
- The class file locator for locating the advisory class's class file.userFactories
- A list of custom factories for user generated offset mappings.public static Advice to(Class<?> enterAdvice, Class<?> exitAdvice)
enterAdvice
- The type declaring the enter advice.exitAdvice
- The type declaring the exit advice.public static Advice to(Class<?> enterAdvice, Class<?> exitAdvice, ClassFileLocator classFileLocator)
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.public static Advice to(TypeDescription enterAdvice, TypeDescription exitAdvice)
false
are resolvable by the returned instance.enterAdvice
- The type declaring the enter advice.exitAdvice
- The type declaring the exit advice.public static Advice to(TypeDescription enterAdvice, TypeDescription exitAdvice, ClassFileLocator classFileLocator)
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.protected static Advice to(TypeDescription enterAdvice, TypeDescription exitAdvice, ClassFileLocator classFileLocator, List<? extends Advice.Dispatcher.OffsetMapping.Factory> userFactories)
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.userFactories
- A list of custom factories for user generated offset mappings.public static Advice.WithCustomMapping withCustomMapping()
Advice
instrumentation with custom values.Advice.DynamicValue
public AsmVisitorWrapper.ForDeclaredMethods on(ElementMatcher<? super MethodDescription.InDefinedShape> matcher)
matcher
- The matcher identifying methods to apply the advice to.public MethodVisitor wrap(TypeDescription instrumentedType, MethodDescription.InDefinedShape methodDescription, MethodVisitor methodVisitor, ClassFileVersion classFileVersion, int writerFlags, int readerFlags)
AsmVisitorWrapper.ForDeclaredMethods.MethodVisitorWrapper
wrap
in interface AsmVisitorWrapper.ForDeclaredMethods.MethodVisitorWrapper
instrumentedType
- The instrumented type.methodDescription
- The method that is currently being defined.methodVisitor
- The original field visitor that defines the given method.classFileVersion
- The class file version of the visited class.writerFlags
- The ASM ClassWriter
reader flags to consider.readerFlags
- The ASM ClassReader
reader flags to consider.Copyright © 2014–2016. All rights reserved.