net.bytebuddy.agent.builder

Class AgentBuilder.Transformer.ForAdvice

java.lang.Object

net.bytebuddy.agent.builder.AgentBuilder.Transformer.ForAdvice

All Implemented Interfaces:

AgentBuilder.Transformer

Enclosing interface:

AgentBuilder.Transformer

@HashCodeAndEqualsPlugin.Enhance
public static class AgentBuilder.Transformer.ForAdvice
extends Object
implements AgentBuilder.Transformer

A transformer for applying an Advice where this advice class might reference types of both the agent's and the user's class loader. Using this transformer, it is possible to apply advice without including any library dependencies of this advice class which are then rather looked up from the transformed class's class loader. For this to work, it is required to register the advice class's class loader manually via the include methods and to reference the advice class by its fully-qualified name. The advice class is then never loaded by rather described by a TypePool.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	AgentBuilder.Transformer.ForAdvice.Entry An entry for an advice to apply.

Nested classes/interfaces inherited from interface net.bytebuddy.agent.builder.AgentBuilder.Transformer

AgentBuilder.Transformer.ForAdvice, AgentBuilder.Transformer.ForBuildPlugin

Constructor Summary

Constructors

Modifier	Constructor and Description
	ForAdvice() Creates a new advice transformer with a default setup.
	ForAdvice(Advice.WithCustomMapping advice) Creates a new advice transformer which applies the given advice.
protected	ForAdvice(Advice.WithCustomMapping advice, Advice.ExceptionHandler exceptionHandler, Assigner assigner, ClassFileLocator classFileLocator, AgentBuilder.PoolStrategy poolStrategy, AgentBuilder.LocationStrategy locationStrategy, List<AgentBuilder.Transformer.ForAdvice.Entry> entries) Creates a new advice transformer.

Method Summary

Modifier and Type	Method and Description
AgentBuilder.Transformer.ForAdvice	advice(ElementMatcher<? super MethodDescription> matcher, String name) Applies the given advice class onto all methods that satisfy the supplied matcher.
AgentBuilder.Transformer.ForAdvice	advice(ElementMatcher<? super MethodDescription> matcher, String enter, String exit) Applies the given advice class onto all methods that satisfy the supplied matcher.
AgentBuilder.Transformer.ForAdvice	advice(LatentMatcher<? super MethodDescription> matcher, String name) Applies the given advice class onto all methods that satisfy the supplied matcher.
AgentBuilder.Transformer.ForAdvice	advice(LatentMatcher<? super MethodDescription> matcher, String enter, String exit) Applies the given advice class onto all methods that satisfy the supplied matcher.
AgentBuilder.Transformer.ForAdvice	include(ClassFileLocator... classFileLocator) Includes the supplied class file locators as a source for looking up an advice class or its dependencies.
AgentBuilder.Transformer.ForAdvice	include(ClassLoader... classLoader) Includes the supplied class loaders as a source for looking up an advice class or its dependencies.
AgentBuilder.Transformer.ForAdvice	include(List<? extends ClassFileLocator> classFileLocators) Includes the supplied class file locators as a source for looking up an advice class or its dependencies.
protected AgentBuilder.Transformer.ForAdvice	make(Advice.WithCustomMapping advice, Advice.ExceptionHandler exceptionHandler, Assigner assigner, ClassFileLocator classFileLocator, AgentBuilder.PoolStrategy poolStrategy, AgentBuilder.LocationStrategy locationStrategy, List<AgentBuilder.Transformer.ForAdvice.Entry> entries) Creates an advice transformer.
DynamicType.Builder<?>	transform(DynamicType.Builder<?> builder, TypeDescription typeDescription, ClassLoader classLoader, JavaModule module, ProtectionDomain protectionDomain) Allows for a transformation of a DynamicType.Builder.
AgentBuilder.Transformer.ForAdvice	with(AgentBuilder.LocationStrategy locationStrategy) Registers a location strategy for creating a ClassFileLocator from the class loader that is supplied during transformation that should be used for looking up advice-relevant classes.
AgentBuilder.Transformer.ForAdvice	with(AgentBuilder.PoolStrategy poolStrategy) Registers a pool strategy for creating a TypePool that should be used for creating the advice class.
AgentBuilder.Transformer.ForAdvice	with(Assigner assigner) Registers an assigner to be used by the advice class.
AgentBuilder.Transformer.ForAdvice	withExceptionHandler(Advice.ExceptionHandler exceptionHandler) Registers an exception handler for suppressed exceptions to use by the registered advice.
protected AsmVisitorWrapper.ForDeclaredMethods.MethodVisitorWrapper	wrap(TypeDescription typeDescription, ClassLoader classLoader, JavaModule module, ProtectionDomain protectionDomain, Advice advice) Allows for decoration of advice for subclass implementations of this transformer.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ForAdvice

public ForAdvice()

Creates a new advice transformer with a default setup.

ForAdvice

public ForAdvice(Advice.WithCustomMapping advice)

Creates a new advice transformer which applies the given advice.

Parameters:

advice - The configured advice to use.

ForAdvice

protected ForAdvice(Advice.WithCustomMapping advice,
                    Advice.ExceptionHandler exceptionHandler,
                    Assigner assigner,
                    ClassFileLocator classFileLocator,
                    AgentBuilder.PoolStrategy poolStrategy,
                    AgentBuilder.LocationStrategy locationStrategy,
                    List<AgentBuilder.Transformer.ForAdvice.Entry> entries)

Creates a new advice transformer.

Parameters:

advice - The configured advice to use.

exceptionHandler - The exception handler to use.

assigner - The assigner to use.

classFileLocator - The class file locator to use.

poolStrategy - The pool strategy to use for looking up an advice.

locationStrategy - The location strategy to use for class loaders when resolving advice classes.

entries - The advice entries to apply.

Method Detail

transform

public DynamicType.Builder<?> transform(DynamicType.Builder<?> builder,
                                        TypeDescription typeDescription,
                                        @MaybeNull
                                        ClassLoader classLoader,
                                        @MaybeNull
                                        JavaModule module,
                                        @MaybeNull
                                        ProtectionDomain protectionDomain)

Allows for a transformation of a DynamicType.Builder.

Specified by:

transform in interface AgentBuilder.Transformer

Parameters:

builder - The dynamic builder to transform.

typeDescription - The description of the type currently being instrumented.

classLoader - The class loader of the instrumented class. Might be null to represent the bootstrap class loader.

module - The class's module or null if the current VM does not support modules.

protectionDomain - The protection domain of the transformed type or null if not available

Returns:

A transformed version of the supplied builder.

wrap

protected AsmVisitorWrapper.ForDeclaredMethods.MethodVisitorWrapper wrap(TypeDescription typeDescription,
                                                                         @MaybeNull
                                                                         ClassLoader classLoader,
                                                                         @MaybeNull
                                                                         JavaModule module,
                                                                         @MaybeNull
                                                                         ProtectionDomain protectionDomain,
                                                                         Advice advice)

Allows for decoration of advice for subclass implementations of this transformer. Note that a subclass is not retained when using the builder methods of this class. Subclasses should also override the make method of this class to allow propagating the custom configuration.

Parameters:

typeDescription - The description of the type currently being instrumented.

classLoader - The class loader of the instrumented class. Might be null to represent the bootstrap class loader.

module - The class's module or null if the current VM does not support modules.

protectionDomain - The protection domain of the transformed type or null if not available

advice - The advice to wrap.

Returns:

A visitor wrapper that represents the supplied advice.

make

protected AgentBuilder.Transformer.ForAdvice make(Advice.WithCustomMapping advice,
                                                  Advice.ExceptionHandler exceptionHandler,
                                                  Assigner assigner,
                                                  ClassFileLocator classFileLocator,
                                                  AgentBuilder.PoolStrategy poolStrategy,
                                                  AgentBuilder.LocationStrategy locationStrategy,
                                                  List<AgentBuilder.Transformer.ForAdvice.Entry> entries)

Creates an advice transformer. This method is to be overridden when overriding the wrap method.

Parameters:

advice - The configured advice to use.

exceptionHandler - The exception handler to use.

assigner - The assigner to use.

classFileLocator - The class file locator to use.

poolStrategy - The pool strategy to use for looking up an advice.

locationStrategy - The location strategy to use for class loaders when resolving advice classes.

entries - The advice entries to apply.

Returns:

An appropriate advice transformer.

with

public AgentBuilder.Transformer.ForAdvice with(AgentBuilder.PoolStrategy poolStrategy)

Registers a pool strategy for creating a TypePool that should be used for creating the advice class.

Parameters:

poolStrategy - The pool strategy to use.

Returns:

A new instance of this advice transformer that applies the supplied pool strategy.

with

public AgentBuilder.Transformer.ForAdvice with(AgentBuilder.LocationStrategy locationStrategy)

Registers a location strategy for creating a ClassFileLocator from the class loader that is supplied during transformation that should be used for looking up advice-relevant classes.

Parameters:

locationStrategy - The location strategy to use.

Returns:

A new instance of this advice transformer that applies the supplied location strategy.

withExceptionHandler

public AgentBuilder.Transformer.ForAdvice withExceptionHandler(Advice.ExceptionHandler exceptionHandler)

Registers an exception handler for suppressed exceptions to use by the registered advice.

Parameters:

exceptionHandler - The exception handler to use.

Returns:

A new instance of this advice transformer that applies the supplied exception handler.

See Also:

Advice.withExceptionHandler(StackManipulation)

with

public AgentBuilder.Transformer.ForAdvice with(Assigner assigner)

Registers an assigner to be used by the advice class.

Parameters:

assigner - The assigner to use.

Returns:

A new instance of this advice transformer that applies the supplied assigner.

See Also:

Advice.withAssigner(Assigner)

include

public AgentBuilder.Transformer.ForAdvice include(ClassLoader... classLoader)

Includes the supplied class loaders as a source for looking up an advice class or its dependencies. Note that the supplied class loaders are queried for types before the class loader of the instrumented class.

Parameters:

classLoader - The class loaders to include when looking up classes in their order. Duplicates are filtered.

Returns:

A new instance of this advice transformer that considers the supplied class loaders as a lookup source.

include

public AgentBuilder.Transformer.ForAdvice include(ClassFileLocator... classFileLocator)

Includes the supplied class file locators as a source for looking up an advice class or its dependencies. Note that the supplied class loaders are queried for types before the class loader of the instrumented class.

Parameters:

classFileLocator - The class file locators to include when looking up classes in their order. Duplicates are filtered.

Returns:

A new instance of this advice transformer that considers the supplied class file locators as a lookup source.

include

public AgentBuilder.Transformer.ForAdvice include(List<? extends ClassFileLocator> classFileLocators)

Includes the supplied class file locators as a source for looking up an advice class or its dependencies. Note that the supplied class loaders are queried for types before the class loader of the instrumented class.

Parameters:

classFileLocators - The class file locators to include when looking up classes in their order. Duplicates are filtered.

Returns:

A new instance of this advice transformer that considers the supplied class file locators as a lookup source.

advice

public AgentBuilder.Transformer.ForAdvice advice(ElementMatcher<? super MethodDescription> matcher,
                                                 String name)

Applies the given advice class onto all methods that satisfy the supplied matcher.

Parameters:

matcher - The matcher to determine what methods the advice should be applied to.

name - The fully-qualified, binary name of the advice class.

Returns:

A new instance of this advice transformer that applies the given advice to all matched methods of an instrumented type.

advice

public AgentBuilder.Transformer.ForAdvice advice(LatentMatcher<? super MethodDescription> matcher,
                                                 String name)

Applies the given advice class onto all methods that satisfy the supplied matcher.

Parameters:

matcher - The matcher to determine what methods the advice should be applied to.

name - The fully-qualified, binary name of the advice class.

Returns:

A new instance of this advice transformer that applies the given advice to all matched methods of an instrumented type.

advice

public AgentBuilder.Transformer.ForAdvice advice(ElementMatcher<? super MethodDescription> matcher,
                                                 String enter,
                                                 String exit)

Applies the given advice class onto all methods that satisfy the supplied matcher.

Parameters:

matcher - The matcher to determine what methods the advice should be applied to.

enter - The fully-qualified, binary name of the enter advice class.

exit - The fully-qualified, binary name of the exit advice class.

Returns:

A new instance of this advice transformer that applies the given advice to all matched methods of an instrumented type.

advice

public AgentBuilder.Transformer.ForAdvice advice(LatentMatcher<? super MethodDescription> matcher,
                                                 String enter,
                                                 String exit)

Applies the given advice class onto all methods that satisfy the supplied matcher.

Parameters:

matcher - The matcher to determine what methods the advice should be applied to.

enter - The fully-qualified, binary name of the enter advice class.

exit - The fully-qualified, binary name of the exit advice class.

Returns:

A new instance of this advice transformer that applies the given advice to all matched methods of an instrumented type.