Class AgentBuilder.Default.Delegator
- All Implemented Interfaces:
AgentBuilder
- Direct Known Subclasses:
AgentBuilder.Default.Delegator.Matchable
,AgentBuilder.Default.Redefining.WithResubmission
- Enclosing class:
AgentBuilder.Default
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprotected static class
An abstract base implementation of a matchable.Nested classes/interfaces inherited from interface net.bytebuddy.agent.builder.AgentBuilder
AgentBuilder.CircularityLock, AgentBuilder.ClassFileBufferStrategy, AgentBuilder.Default, AgentBuilder.DescriptionStrategy, AgentBuilder.FallbackStrategy, AgentBuilder.Identified, AgentBuilder.Ignored, AgentBuilder.InitializationStrategy, AgentBuilder.InjectionStrategy, AgentBuilder.InstallationListener, AgentBuilder.LambdaInstrumentationStrategy, AgentBuilder.Listener, AgentBuilder.LocationStrategy, AgentBuilder.PatchMode, AgentBuilder.PoolStrategy, AgentBuilder.RawMatcher, AgentBuilder.RedefinitionListenable, AgentBuilder.RedefinitionStrategy, AgentBuilder.Transformer, AgentBuilder.TransformerDecorator, AgentBuilder.TypeStrategy
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionassureReadEdgeFromAndTo
(Instrumentation instrumentation, Class<?>... type) Assures that all modules of the supplied types are read by the module of any instrumented type and vice versa.assureReadEdgeFromAndTo
(Instrumentation instrumentation, Collection<? extends JavaModule> modules) Assures that all supplied modules are read by the module of any instrumented type and vice versa.assureReadEdgeFromAndTo
(Instrumentation instrumentation, JavaModule... module) Assures that all supplied modules are read by the module of any instrumented type and vice versa.assureReadEdgeTo
(Instrumentation instrumentation, Class<?>... type) Assures that all modules of the supplied types are read by the module of any instrumented type.assureReadEdgeTo
(Instrumentation instrumentation, Collection<? extends JavaModule> modules) Assures that all supplied modules are read by the module of any instrumented type.assureReadEdgeTo
(Instrumentation instrumentation, JavaModule... module) Assures that all supplied modules are read by the module of any instrumented type.Disables all implicit changes on a class file that Byte Buddy would apply for certain instrumentations.Disables the use of a native method prefix for instrumented methods.enableNativeMethodPrefix
(String prefix) Enables the use of the given native method prefix for instrumented methods.ignore
(AgentBuilder.RawMatcher rawMatcher) Excludes any type that is matched by the raw matcher provided to this method.ignore
(ElementMatcher<? super TypeDescription> ignoredTypes) Excludes any type that is matched by the provided matcher from instrumentation and considers types by allClassLoader
s.ignore
(ElementMatcher<? super TypeDescription> ignoredTypes, ElementMatcher<? super ClassLoader> ignoredClassLoaders) Excludes any type that is matched by the provided matcher and is loaded by a class loader matching the second matcher.ignore
(ElementMatcher<? super TypeDescription> typeMatcher, ElementMatcher<? super ClassLoader> classLoaderMatcher, ElementMatcher<? super JavaModule> moduleMatcher) Excludes any type that is matched by the provided matcher and is loaded by a class loader matching the second matcher.installOn
(Instrumentation instrumentation) Creates and installs aResettableClassFileTransformer
that implements the configuration of this agent builder with a givenInstrumentation
.Creates and installs aResettableClassFileTransformer
that implements the configuration of this agent builder with the Byte Buddy-agent which must be installed prior to calling this method.makeRaw()
Creates aResettableClassFileTransformer
that implements the configuration of this agent builder.protected abstract AgentBuilder
Materializes the currently describedAgentBuilder
.patchOn
(Instrumentation instrumentation, ResettableClassFileTransformer classFileTransformer) Creates and installs aResettableClassFileTransformer
that implements the configuration of this agent builder with a givenInstrumentation
.patchOn
(Instrumentation instrumentation, ResettableClassFileTransformer classFileTransformer, AgentBuilder.PatchMode patchMode) Creates and installs aResettableClassFileTransformer
that implements the configuration of this agent builder with a givenInstrumentation
.patchOn
(Instrumentation instrumentation, ResettableClassFileTransformer classFileTransformer, AgentBuilder.RawMatcher differentialMatcher) Creates and installs aResettableClassFileTransformer
that implements the configuration of this agent builder with a givenInstrumentation
.patchOn
(Instrumentation instrumentation, ResettableClassFileTransformer classFileTransformer, AgentBuilder.RawMatcher differentialMatcher, AgentBuilder.PatchMode patchMode) Creates and installs aResettableClassFileTransformer
that implements the configuration of this agent builder with a givenInstrumentation
.patchOnByteBuddyAgent
(ResettableClassFileTransformer classFileTransformer) Creates and installs aResettableClassFileTransformer
that implements the configuration of this agent builder with the Byte Buddy-agent which must be installed prior to calling this method.patchOnByteBuddyAgent
(ResettableClassFileTransformer classFileTransformer, AgentBuilder.PatchMode patchMode) Creates and installs aResettableClassFileTransformer
that implements the configuration of this agent builder with the Byte Buddy-agent which must be installed prior to calling this method.type
(AgentBuilder.RawMatcher matcher) Matches a type being loaded in order to apply the suppliedAgentBuilder.Transformer
s before loading this type.type
(ElementMatcher<? super TypeDescription> typeMatcher) Matches a type being loaded in order to apply the suppliedAgentBuilder.Transformer
s before loading this type.type
(ElementMatcher<? super TypeDescription> typeMatcher, ElementMatcher<? super ClassLoader> classLoaderMatcher) Matches a type being loaded in order to apply the suppliedAgentBuilder.Transformer
s before loading this type.type
(ElementMatcher<? super TypeDescription> typeMatcher, ElementMatcher<? super ClassLoader> classLoaderMatcher, ElementMatcher<? super JavaModule> moduleMatcher) Matches a type being loaded in order to apply the suppliedAgentBuilder.Transformer
s before loading this type.Warms up the generatedClassFileTransformer
to trigger class loading of classes used by the transformer prior to its actual use.warmUp
(Collection<Class<?>> types) Warms up the generatedClassFileTransformer
to trigger class loading of classes used by the transformer prior to its actual use.with
(AgentBuilder.CircularityLock circularityLock) Defines a circularity lock that is acquired upon executing code that potentially loads new classes.with
(AgentBuilder.ClassFileBufferStrategy classFileBufferStrategy) Specifies a class file buffer strategy that determines the use of the buffer supplied to a class file transformer.with
(AgentBuilder.DescriptionStrategy descriptionStrategy) Specifies a strategy to be used for resolvingTypeDescription
for any type handled by the created transformer.with
(AgentBuilder.FallbackStrategy fallbackStrategy) Specifies a fallback strategy to that this agent builder applies upon installing an agent and during class file transformation.with
(AgentBuilder.InitializationStrategy initializationStrategy) Defines a given initialization strategy to be applied to generated types.with
(AgentBuilder.InjectionStrategy injectionStrategy) Defines a strategy for injecting auxiliary types into the target class loader.with
(AgentBuilder.InstallationListener installationListener) Adds an installation listener that is notified during installation events.with
(AgentBuilder.LambdaInstrumentationStrategy lambdaInstrumentationStrategy) Enables or disables management of the JVM'sLambdaMetafactory
which is responsible for creating classes that implement lambda expressions.with
(AgentBuilder.Listener listener) Defines the givenAgentBuilder.Listener
to be notified by the created agent.with
(AgentBuilder.LocationStrategy locationStrategy) Defines the use of the given location strategy for locating binary data to given class names.with
(AgentBuilder.PoolStrategy poolStrategy) Defines the use of the given type locator for locating aTypeDescription
for an instrumented type.with
(AgentBuilder.RedefinitionStrategy redefinitionStrategy) Specifies a strategy for modifying types that were already loaded prior to the installation of this transformer.with
(AgentBuilder.TransformerDecorator transformerDecorator) Adds a decorator for the created class file transformer.with
(AgentBuilder.TypeStrategy typeStrategy) Defines how types should be transformed, e.g.Defines the givenByteBuddy
instance to be used by the created agent.with
(ClassFileLocator classFileLocator) Registers an additional class file locator for types that are globally available but cannot be located otherwise.
-
Constructor Details
-
Delegator
protected Delegator()
-
-
Method Details
-
materialize
Materializes the currently describedAgentBuilder
.- Returns:
- An agent builder that represents the currently described entry of this instance.
-
with
Defines the givenByteBuddy
instance to be used by the created agent.- Specified by:
with
in interfaceAgentBuilder
- Parameters:
byteBuddy
- The Byte Buddy instance to be used.- Returns:
- A new instance of this agent builder which makes use of the given
byteBuddy
instance.
-
with
Defines the givenAgentBuilder.Listener
to be notified by the created agent. The given listener is notified after any other listener that is already registered. If a listener is registered twice, it is also notified twice.- Specified by:
with
in interfaceAgentBuilder
- Parameters:
listener
- The listener to be notified.- Returns:
- A new instance of this agent builder which creates an agent that informs the given listener about events.
-
with
Defines a circularity lock that is acquired upon executing code that potentially loads new classes. While the lock is acquired, any class file transformer refrains from transforming any classes. By default, all created agents use a sharedAgentBuilder.CircularityLock
to avoid that any classes that are required to execute an agent causes aClassCircularityError
.- Specified by:
with
in interfaceAgentBuilder
- Parameters:
circularityLock
- The circularity lock to use.- Returns:
- A new instance of this agent builder which creates an agent that uses the supplied circularity lock.
-
with
Defines how types should be transformed, e.g. if they should be rebased or redefined by the created agent.- Specified by:
with
in interfaceAgentBuilder
- Parameters:
typeStrategy
- The type strategy to use.- Returns:
- A new instance of this agent builder which uses the given type strategy.
-
with
Defines the use of the given type locator for locating aTypeDescription
for an instrumented type.- Specified by:
with
in interfaceAgentBuilder
- Parameters:
poolStrategy
- The type locator to use.- Returns:
- A new instance of this agent builder which uses the given type locator for looking up class files.
-
with
Defines the use of the given location strategy for locating binary data to given class names.- Specified by:
with
in interfaceAgentBuilder
- Parameters:
locationStrategy
- The location strategy to use.- Returns:
- A new instance of this agent builder which uses the given location strategy for looking up class files.
-
with
Registers an additional class file locator for types that are globally available but cannot be located otherwise. Typically, those types are injected classes into the boot loader.- Specified by:
with
in interfaceAgentBuilder
- Parameters:
classFileLocator
- The class file locator to add.- Returns:
- A new instance of this agent builder which uses the given class file locator for global type lookup.
-
with
Defines a given initialization strategy to be applied to generated types. An initialization strategy is responsible for setting up a type after it was loaded. This initialization must be performed after the transformation because a Java agent is only invoked before loading a type. By default, the initialization logic is added to a class's type initializer which queries a global object for any objects that are to be injected into the generated type.- Specified by:
with
in interfaceAgentBuilder
- Parameters:
initializationStrategy
- The initialization strategy to use.- Returns:
- A new instance of this agent builder that applies the given initialization strategy.
-
with
public AgentBuilder.RedefinitionListenable.WithoutBatchStrategy with(AgentBuilder.RedefinitionStrategy redefinitionStrategy) Specifies a strategy for modifying types that were already loaded prior to the installation of this transformer.
Note: Defining a redefinition strategy resets any refinements of a previously set redefinition strategy.
Important: Most JVMs do not support changes of a class's structure after a class was already loaded. Therefore, it is typically required that this class file transformer was built while enabling
AgentBuilder.disableClassFormatChanges()
.- Specified by:
with
in interfaceAgentBuilder
- Parameters:
redefinitionStrategy
- The redefinition strategy to apply.- Returns:
- A new instance of this agent builder that applies the given redefinition strategy.
-
with
Enables or disables management of the JVM's
LambdaMetafactory
which is responsible for creating classes that implement lambda expressions. Without this feature enabled, classes that are represented by lambda expressions are not instrumented by the JVM such that Java agents have no effect on them when a lambda expression's class is loaded for the first time.When activating this feature, Byte Buddy instruments the
LambdaMetafactory
and takes over the responsibility of creating classes that represent lambda expressions. In doing so, Byte Buddy has the opportunity to apply the built class file transformer. If the current VM does not support lambda expressions, activating this feature has no effect.Important: If this feature is active, it is important to release the built class file transformer when deactivating it. Normally, it is sufficient to call
Instrumentation.removeTransformer(ClassFileTransformer)
. When this feature is enabled, it is however also required to invokeAgentBuilder.LambdaInstrumentationStrategy.release(ClassFileTransformer, Instrumentation)
. Otherwise, the executing VMs class loader retains a reference to the class file transformer what can cause a memory leak.- Specified by:
with
in interfaceAgentBuilder
- Parameters:
lambdaInstrumentationStrategy
-true
if this feature should be enabled.- Returns:
- A new instance of this agent builder where this feature is explicitly enabled or disabled.
-
with
Specifies a strategy to be used for resolvingTypeDescription
for any type handled by the created transformer.- Specified by:
with
in interfaceAgentBuilder
- Parameters:
descriptionStrategy
- The description strategy to use.- Returns:
- A new instance of this agent builder that applies the given description strategy.
-
with
Specifies a fallback strategy to that this agent builder applies upon installing an agent and during class file transformation.- Specified by:
with
in interfaceAgentBuilder
- Parameters:
fallbackStrategy
- The fallback strategy to be used.- Returns:
- A new agent builder that applies the supplied fallback strategy.
-
with
Specifies a class file buffer strategy that determines the use of the buffer supplied to a class file transformer.- Specified by:
with
in interfaceAgentBuilder
- Parameters:
classFileBufferStrategy
- The class file buffer strategy to use.- Returns:
- A new agent builder that applies the supplied class file buffer strategy.
-
with
Adds an installation listener that is notified during installation events. Installation listeners are only invoked if a class file transformer is installed using this agent builder's installation methods and uninstalled via the createdResettableClassFileTransformer
'sreset
methods.- Specified by:
with
in interfaceAgentBuilder
- Parameters:
installationListener
- The installation listener to register.- Returns:
- A new agent builder that applies the supplied installation listener.
-
with
Defines a strategy for injecting auxiliary types into the target class loader.- Specified by:
with
in interfaceAgentBuilder
- Parameters:
injectionStrategy
- The injection strategy to use.- Returns:
- A new agent builder with the supplied injection strategy configured.
-
with
Adds a decorator for the created class file transformer.- Specified by:
with
in interfaceAgentBuilder
- Parameters:
transformerDecorator
- A decorator to wrap the created class file transformer.- Returns:
- A new agent builder that applies the supplied transformer decorator.
-
enableNativeMethodPrefix
Enables the use of the given native method prefix for instrumented methods. Note that this prefix is also applied when preserving non-native methods. The use of this prefix is also registered when installing the final agent with anInstrumentation
.- Specified by:
enableNativeMethodPrefix
in interfaceAgentBuilder
- Parameters:
prefix
- The prefix to be used.- Returns:
- A new instance of this agent builder which uses the given native method prefix.
-
disableNativeMethodPrefix
Disables the use of a native method prefix for instrumented methods.- Specified by:
disableNativeMethodPrefix
in interfaceAgentBuilder
- Returns:
- A new instance of this agent builder which does not use a native method prefix.
-
disableClassFormatChanges
Disables all implicit changes on a class file that Byte Buddy would apply for certain instrumentations. When using this option, it is no longer possible to rebase a method, i.e. intercepted methods are fully replaced. Furthermore, it is no longer possible to implicitly apply loaded type initializers for explicitly initializing the generated type.
This is equivalent to setting
AgentBuilder.InitializationStrategy.NoOp
andAgentBuilder.TypeStrategy.Default.REDEFINE_FROZEN
(unless it is configured asAgentBuilder.TypeStrategy.Default.DECORATE
where this strategy is retained) as well as configuring the underlyingByteBuddy
instance to use aImplementation.Context.Disabled
. Using this strategy also configures Byte Buddy to create frozen instrumented types and discards any explicit configuration.- Specified by:
disableClassFormatChanges
in interfaceAgentBuilder
- Returns:
- A new instance of this agent builder that does not apply any implicit changes to the received class file.
-
warmUp
Warms up the generated
ClassFileTransformer
to trigger class loading of classes used by the transformer prior to its actual use. Ideally, warmup should include classes that cause a transformation and classes that are ignored. Warming up can be especially useful when transforming classes on the boot path, where circularity errors are more likely. At the same time, warming up might load classes that are expected to be unloaded when this agent is installed.Important: Warming up is applied just as a regular transformation and will also invoke the
AgentBuilder.Listener
. This is done to avoid that listener classes can cause circularities. It is the users responsibility to suppress such log output, if necessary.- Specified by:
warmUp
in interfaceAgentBuilder
- Parameters:
type
- The types to include in the warmup.- Returns:
- A new agent builder that considers the supplied classes in its warmup.
-
warmUp
Warms up the generated
ClassFileTransformer
to trigger class loading of classes used by the transformer prior to its actual use. Ideally, warmup should include classes that cause a transformation and classes that are ignored. Warming up can be especially useful when transforming classes on the boot path, where circularity errors are more likely. At the same time, warming up might load classes that are expected to be unloaded when this agent is installed.Important: Warming up is applied just as a regular transformation and will also invoke the
AgentBuilder.Listener
. This is done to avoid that listener classes can cause circularities. It is the users responsibility to suppress such log output, if necessary.- Specified by:
warmUp
in interfaceAgentBuilder
- Parameters:
types
- The types to include in the warmup.- Returns:
- A new agent builder that considers the supplied classes in its warmup.
-
assureReadEdgeTo
Assures that all modules of the supplied types are read by the module of any instrumented type. If the current VM does not support the Java module system, calling this method has no effect and this instance is returned.- Specified by:
assureReadEdgeTo
in interfaceAgentBuilder
- Parameters:
instrumentation
- The instrumentation instance that is used for adding a module read-dependency.type
- The types for which to assure their module-visibility from any instrumented class.- Returns:
- A new instance of this agent builder that assures the supplied types module visibility.
- See Also:
-
assureReadEdgeTo
Assures that all supplied modules are read by the module of any instrumented type.- Specified by:
assureReadEdgeTo
in interfaceAgentBuilder
- Parameters:
instrumentation
- The instrumentation instance that is used for adding a module read-dependency.module
- The modules for which to assure their module-visibility from any instrumented class.- Returns:
- A new instance of this agent builder that assures the supplied types module visibility.
- See Also:
-
assureReadEdgeTo
public AgentBuilder assureReadEdgeTo(Instrumentation instrumentation, Collection<? extends JavaModule> modules) Assures that all supplied modules are read by the module of any instrumented type.- Specified by:
assureReadEdgeTo
in interfaceAgentBuilder
- Parameters:
instrumentation
- The instrumentation instance that is used for adding a module read-dependency.modules
- The modules for which to assure their module-visibility from any instrumented class.- Returns:
- A new instance of this agent builder that assures the supplied types module visibility.
- See Also:
-
assureReadEdgeFromAndTo
Assures that all modules of the supplied types are read by the module of any instrumented type and vice versa. If the current VM does not support the Java module system, calling this method has no effect and this instance is returned. Setting this option will also ensure that the instrumented type's package is opened to the target module, if applicable.- Specified by:
assureReadEdgeFromAndTo
in interfaceAgentBuilder
- Parameters:
instrumentation
- The instrumentation instance that is used for adding a module read-dependency.type
- The types for which to assure their module-visibility from and to any instrumented class.- Returns:
- A new instance of this agent builder that assures the supplied types module visibility.
- See Also:
-
assureReadEdgeFromAndTo
Assures that all supplied modules are read by the module of any instrumented type and vice versa. Setting this option will also ensure that the instrumented type's package is opened to the target module.- Specified by:
assureReadEdgeFromAndTo
in interfaceAgentBuilder
- Parameters:
instrumentation
- The instrumentation instance that is used for adding a module read-dependency.module
- The modules for which to assure their module-visibility from and to any instrumented class.- Returns:
- A new instance of this agent builder that assures the supplied types module visibility.
- See Also:
-
assureReadEdgeFromAndTo
public AgentBuilder assureReadEdgeFromAndTo(Instrumentation instrumentation, Collection<? extends JavaModule> modules) Assures that all supplied modules are read by the module of any instrumented type and vice versa. Setting this option will also ensure that the instrumented type's package is opened to the target module.- Specified by:
assureReadEdgeFromAndTo
in interfaceAgentBuilder
- Parameters:
instrumentation
- The instrumentation instance that is used for adding a module read-dependency.modules
- The modules for which to assure their module-visibility from and to any instrumented class.- Returns:
- A new instance of this agent builder that assures the supplied types module visibility.
- See Also:
-
type
Matches a type being loaded in order to apply the supplied
AgentBuilder.Transformer
s before loading this type. If several matchers positively match a type only the latest registered matcher is considered for transformation.If this matcher is chained with additional subsequent matchers, any matcher is executed in registration order with matchers that were registered first being executed first. Doing so, later transformations can override transformations that are applied by this matcher. To avoid this, it is possible to register this transformation as terminal via
AgentBuilder.Identified.Extendable.asTerminalTransformation()
where no subsequent matchers are applied if this matcher matched a given type.Note: When applying a matcher, regard the performance implications by
AgentBuilder.ignore(ElementMatcher)
. The former matcher is applied first such that it makes sense to ignore name spaces that are irrelevant to instrumentation. If possible, it is also recommended, to exclude class loaders such as for example the bootstrap class loader by usingAgentBuilder.type(ElementMatcher, ElementMatcher)
instead.- Specified by:
type
in interfaceAgentBuilder
- Parameters:
typeMatcher
- AnElementMatcher
that is applied on the type being loaded that decides if the entailedAgentBuilder.Transformer
s should be applied for that type.- Returns:
- A definable that represents this agent builder which allows for the definition of one or several
AgentBuilder.Transformer
s to be applied when the giventypeMatcher
indicates a match.
-
type
public AgentBuilder.Identified.Narrowable type(ElementMatcher<? super TypeDescription> typeMatcher, ElementMatcher<? super ClassLoader> classLoaderMatcher) Matches a type being loaded in order to apply the supplied
AgentBuilder.Transformer
s before loading this type. If several matchers positively match a type only the latest registered matcher is considered for transformation.If this matcher is chained with additional subsequent matchers, any matcher is executed in registration order with matchers that were registered first being executed first. Doing so, later transformations can override transformations that are applied by this matcher. To avoid this, it is possible to register this transformation as terminal via
AgentBuilder.Identified.Extendable.asTerminalTransformation()
where no subsequent matchers are applied if this matcher matched a given type.Note: When applying a matcher, regard the performance implications by
AgentBuilder.ignore(ElementMatcher)
. The former matcher is applied first such that it makes sense to ignore name spaces that are irrelevant to instrumentation. If possible, it is also recommended, to exclude class loaders such as for example the bootstrap class loader.- Specified by:
type
in interfaceAgentBuilder
- Parameters:
typeMatcher
- AnElementMatcher
that is applied on the type being loaded that decides if the entailedAgentBuilder.Transformer
s should be applied for that type.classLoaderMatcher
- AnElementMatcher
that is applied to theClassLoader
that is loading the type being loaded. This matcher is always applied first where the type matcher is not applied in case that this matcher does not indicate a match.- Returns:
- A definable that represents this agent builder which allows for the definition of one or several
AgentBuilder.Transformer
s to be applied when both the giventypeMatcher
andclassLoaderMatcher
indicate a match.
-
type
public AgentBuilder.Identified.Narrowable type(ElementMatcher<? super TypeDescription> typeMatcher, ElementMatcher<? super ClassLoader> classLoaderMatcher, ElementMatcher<? super JavaModule> moduleMatcher) Matches a type being loaded in order to apply the supplied
AgentBuilder.Transformer
s before loading this type. If several matchers positively match a type only the latest registered matcher is considered for transformation.If this matcher is chained with additional subsequent matchers, any matcher is executed in registration order with matchers that were registered first being executed first. Doing so, later transformations can override transformations that are applied by this matcher. To avoid this, it is possible to register this transformation as terminal via
AgentBuilder.Identified.Extendable.asTerminalTransformation()
where no subsequent matchers are applied if this matcher matched a given type.Note: When applying a matcher, regard the performance implications by
AgentBuilder.ignore(ElementMatcher)
. The former matcher is applied first such that it makes sense to ignore name spaces that are irrelevant to instrumentation. If possible, it is also recommended, to exclude class loaders such as for example the bootstrap class loader.- Specified by:
type
in interfaceAgentBuilder
- Parameters:
typeMatcher
- AnElementMatcher
that is applied on the type being loaded that decides if the entailedAgentBuilder.Transformer
s should be applied for that type.classLoaderMatcher
- AnElementMatcher
that is applied to theClassLoader
that is loading the type being loaded. This matcher is always applied second where the type matcher is not applied in case that this matcher does not indicate a match.moduleMatcher
- AnElementMatcher
that is applied to theJavaModule
of the type being loaded. This matcher is always applied first where the class loader and type matchers are not applied in case that this matcher does not indicate a match. On a JVM that does not support the Java modules system, this matcher is not applied.- Returns:
- A definable that represents this agent builder which allows for the definition of one or several
AgentBuilder.Transformer
s to be applied when both the giventypeMatcher
andclassLoaderMatcher
indicate a match.
-
type
Matches a type being loaded in order to apply the supplied
AgentBuilder.Transformer
s before loading this type. If several matchers positively match a type only the latest registered matcher is considered for transformation.If this matcher is chained with additional subsequent matchers, any matcher is executed in registration order with matchers that were registered first being executed first. Doing so, later transformations can override transformations that are applied by this matcher. To avoid this, it is possible to register this transformation as terminal via
AgentBuilder.Identified.Extendable.asTerminalTransformation()
where no subsequent matchers are applied if this matcher matched a given type.Note: When applying a matcher, regard the performance implications by
AgentBuilder.ignore(ElementMatcher)
. The former matcher is applied first such that it makes sense to ignore name spaces that are irrelevant to instrumentation. If possible, it is also recommended, to exclude class loaders such as for example the bootstrap class loader.- Specified by:
type
in interfaceAgentBuilder
- Parameters:
matcher
- A matcher that decides if the entailedAgentBuilder.Transformer
s should be applied for a type that is being loaded.- Returns:
- A definable that represents this agent builder which allows for the definition of one or several
AgentBuilder.Transformer
s to be applied when the givenmatcher
indicates a match.
-
ignore
Excludes any type that is matched by the provided matcher from instrumentation and considers types by all
ClassLoader
s. By default, Byte Buddy does not instrument synthetic types or types that are loaded by the bootstrap class loader.When ignoring a type, any subsequently chained matcher is applied after this matcher in the order of their registration. Also, if any matcher indicates that a type is to be ignored, none of the following chained matchers is executed.
Note: For performance reasons, it is recommended to always include a matcher that excludes as many namespaces as possible. Byte Buddy can determine a type's name without parsing its class file and can therefore discard such types with minimal overhead. When a different property of a type - such as for example its modifiers or its annotations is accessed - Byte Buddy parses the class file lazily in order to allow for such a matching. Therefore, any exclusion of a name should always be done as a first step and even if it does not influence the selection of what types are matched. Without changing this property, the class file of every type is being parsed!
Warning: If a type is loaded during the instrumentation of the same type, this causes the original call site that loads the type to remain unbound, causing a
LinkageError
. It is therefore important to not instrument types that may be loaded during the application of aAgentBuilder.Transformer
. For this reason, it is not recommended to instrument classes of the bootstrap class loader that Byte Buddy might require for instrumenting a class or to instrument any of Byte Buddy's classes. If such instrumentation is desired, it is important to assert for each class that they are not loaded during instrumentation.- Specified by:
ignore
in interfaceAgentBuilder
- Parameters:
ignoredTypes
- A matcher that identifies types that should not be instrumented.- Returns:
- A new instance of this agent builder that ignores all types that are matched by the provided matcher. All previous matchers for ignored types are discarded.
-
ignore
public AgentBuilder.Ignored ignore(ElementMatcher<? super TypeDescription> ignoredTypes, ElementMatcher<? super ClassLoader> ignoredClassLoaders) Excludes any type that is matched by the provided matcher and is loaded by a class loader matching the second matcher. By default, Byte Buddy does not instrument synthetic types, types within a
net.bytebuddy.*
package or types that are loaded by the bootstrap class loader.When ignoring a type, any subsequently chained matcher is applied after this matcher in the order of their registration. Also, if any matcher indicates that a type is to be ignored, none of the following chained matchers is executed.
Note: For performance reasons, it is recommended to always include a matcher that excludes as many namespaces as possible. Byte Buddy can determine a type's name without parsing its class file and can therefore discard such types with minimal overhead. When a different property of a type - such as for example its modifiers or its annotations is accessed - Byte Buddy parses the class file lazily in order to allow for such a matching. Therefore, any exclusion of a name should always be done as a first step and even if it does not influence the selection of what types are matched. Without changing this property, the class file of every type is being parsed!
Warning: If a type is loaded during the instrumentation of the same type, this causes the original call site that loads the type to remain unbound, causing a
LinkageError
. It is therefore important to not instrument types that may be loaded during the application of aAgentBuilder.Transformer
. For this reason, it is not recommended to instrument classes of the bootstrap class loader that Byte Buddy might require for instrumenting a class or to instrument any of Byte Buddy's classes. If such instrumentation is desired, it is important to assert for each class that they are not loaded during instrumentation.- Specified by:
ignore
in interfaceAgentBuilder
- Parameters:
ignoredTypes
- A matcher that identifies types that should not be instrumented.ignoredClassLoaders
- A matcher that identifies a class loader that identifies classes that should not be instrumented.- Returns:
- A new instance of this agent builder that ignores all types that are matched by the provided matcher. All previous matchers for ignored types are discarded.
-
ignore
public AgentBuilder.Ignored ignore(ElementMatcher<? super TypeDescription> typeMatcher, ElementMatcher<? super ClassLoader> classLoaderMatcher, ElementMatcher<? super JavaModule> moduleMatcher) Excludes any type that is matched by the provided matcher and is loaded by a class loader matching the second matcher. By default, Byte Buddy does not instrument synthetic types, types within a
net.bytebuddy.*
package or types that are loaded by the bootstrap class loader.When ignoring a type, any subsequently chained matcher is applied after this matcher in the order of their registration. Also, if any matcher indicates that a type is to be ignored, none of the following chained matchers is executed.
Note: For performance reasons, it is recommended to always include a matcher that excludes as many namespaces as possible. Byte Buddy can determine a type's name without parsing its class file and can therefore discard such types with minimal overhead. When a different property of a type - such as for example its modifiers or its annotations is accessed - Byte Buddy parses the class file lazily in order to allow for such a matching. Therefore, any exclusion of a name should always be done as a first step and even if it does not influence the selection of what types are matched. Without changing this property, the class file of every type is being parsed!
Warning: If a type is loaded during the instrumentation of the same type, this causes the original call site that loads the type to remain unbound, causing a
LinkageError
. It is therefore important to not instrument types that may be loaded during the application of aAgentBuilder.Transformer
. For this reason, it is not recommended to instrument classes of the bootstrap class loader that Byte Buddy might require for instrumenting a class or to instrument any of Byte Buddy's classes. If such instrumentation is desired, it is important to assert for each class that they are not loaded during instrumentation.- Specified by:
ignore
in interfaceAgentBuilder
- Parameters:
typeMatcher
- A matcher that identifies types that should not be instrumented.classLoaderMatcher
- A matcher that identifies a class loader that identifies classes that should not be instrumented.moduleMatcher
- A matcher that identifies a module that identifies classes that should not be instrumented. On a JVM that does not support the Java modules system, this matcher is not applied.- Returns:
- A new instance of this agent builder that ignores all types that are matched by the provided matcher. All previous matchers for ignored types are discarded.
-
ignore
Excludes any type that is matched by the raw matcher provided to this method. By default, Byte Buddy does not instrument synthetic types, types within a
net.bytebuddy.*
package or types that are loaded by the bootstrap class loader.When ignoring a type, any subsequently chained matcher is applied after this matcher in the order of their registration. Also, if any matcher indicates that a type is to be ignored, none of the following chained matchers is executed.
Note: For performance reasons, it is recommended to always include a matcher that excludes as many namespaces as possible. Byte Buddy can determine a type's name without parsing its class file and can therefore discard such types with minimal overhead. When a different property of a type - such as for example its modifiers or its annotations is accessed - Byte Buddy parses the class file lazily in order to allow for such a matching. Therefore, any exclusion of a name should always be done as a first step and even if it does not influence the selection of what types are matched. Without changing this property, the class file of every type is being parsed!
Warning: If a type is loaded during the instrumentation of the same type, this causes the original call site that loads the type to remain unbound, causing a
LinkageError
. It is therefore important to not instrument types that may be loaded during the application of aAgentBuilder.Transformer
. For this reason, it is not recommended to instrument classes of the bootstrap class loader that Byte Buddy might require for instrumenting a class or to instrument any of Byte Buddy's classes. If such instrumentation is desired, it is important to assert for each class that they are not loaded during instrumentation.- Specified by:
ignore
in interfaceAgentBuilder
- Parameters:
rawMatcher
- A raw matcher that identifies types that should not be instrumented.- Returns:
- A new instance of this agent builder that ignores all types that are matched by the provided matcher. All previous matchers for ignored types are discarded.
-
makeRaw
Creates aResettableClassFileTransformer
that implements the configuration of this agent builder. When using a raw class file transformer, theAgentBuilder.InstallationListener
callbacks are not invoked and the setAgentBuilder.RedefinitionStrategy
is not applied onto currently loaded classes.- Specified by:
makeRaw
in interfaceAgentBuilder
- Returns:
- A class file transformer that implements the configuration of this agent builder.
-
installOn
Creates and installs a
ResettableClassFileTransformer
that implements the configuration of this agent builder with a givenInstrumentation
. If retransformation is enabled, the installation also causes all loaded types to be retransformed.In order to assure the correct handling of the
AgentBuilder.InstallationListener
, an uninstallation should be applied via theResettableClassFileTransformer
'sreset
methods.- Specified by:
installOn
in interfaceAgentBuilder
- Parameters:
instrumentation
- The instrumentation on which this agent builder's configuration is to be installed.- Returns:
- The installed class file transformer.
-
installOnByteBuddyAgent
Creates and installs a
ResettableClassFileTransformer
that implements the configuration of this agent builder with the Byte Buddy-agent which must be installed prior to calling this method. If retransformation is enabled, the installation also causes all loaded types to be retransformed.In order to assure the correct handling of the
AgentBuilder.InstallationListener
, an uninstallation should be applied via theResettableClassFileTransformer
'sreset
methods.- Specified by:
installOnByteBuddyAgent
in interfaceAgentBuilder
- Returns:
- The installed class file transformer.
- See Also:
-
patchOn
public ResettableClassFileTransformer patchOn(Instrumentation instrumentation, ResettableClassFileTransformer classFileTransformer) Creates and installs a
ResettableClassFileTransformer
that implements the configuration of this agent builder with a givenInstrumentation
. If retransformation is enabled, the installation also causes all loaded types to be retransformed which have changed compared to the previous class file transformer that is provided as an argument. Without specification,AgentBuilder.PatchMode.OVERLAP
is used.In order to assure the correct handling of the
AgentBuilder.InstallationListener
, an uninstallation should be applied via theResettableClassFileTransformer
'sreset
methods.- Specified by:
patchOn
in interfaceAgentBuilder
- Parameters:
instrumentation
- The instrumentation on which this agent builder's configuration is to be installed.classFileTransformer
- The class file transformer that is being patched.- Returns:
- The installed class file transformer.
-
patchOn
public ResettableClassFileTransformer patchOn(Instrumentation instrumentation, ResettableClassFileTransformer classFileTransformer, AgentBuilder.RawMatcher differentialMatcher) Creates and installs a
ResettableClassFileTransformer
that implements the configuration of this agent builder with a givenInstrumentation
. If retransformation is enabled, the installation also causes all loaded types to be retransformed which have changed compared to the previous class file transformer that is provided as an argument. Without specification,AgentBuilder.PatchMode.OVERLAP
is used.In order to assure the correct handling of the
AgentBuilder.InstallationListener
, an uninstallation should be applied via theResettableClassFileTransformer
'sreset
methods.- Specified by:
patchOn
in interfaceAgentBuilder
- Parameters:
instrumentation
- The instrumentation on which this agent builder's configuration is to be installed.classFileTransformer
- The class file transformer that is being patched.differentialMatcher
- The differential matcher to decide what types need retransformation.- Returns:
- The installed class file transformer.
-
patchOn
public ResettableClassFileTransformer patchOn(Instrumentation instrumentation, ResettableClassFileTransformer classFileTransformer, AgentBuilder.PatchMode patchMode) Creates and installs a
ResettableClassFileTransformer
that implements the configuration of this agent builder with a givenInstrumentation
. If retransformation is enabled, the installation also causes all loaded types to be retransformed which have changed compared to the previous class file transformer that is provided as an argument.In order to assure the correct handling of the
AgentBuilder.InstallationListener
, an uninstallation should be applied via theResettableClassFileTransformer
'sreset
methods.- Specified by:
patchOn
in interfaceAgentBuilder
- Parameters:
instrumentation
- The instrumentation on which this agent builder's configuration is to be installed.classFileTransformer
- The class file transformer that is being patched.patchMode
- The patch mode to apply.- Returns:
- The installed class file transformer.
-
patchOn
public ResettableClassFileTransformer patchOn(Instrumentation instrumentation, ResettableClassFileTransformer classFileTransformer, AgentBuilder.RawMatcher differentialMatcher, AgentBuilder.PatchMode patchMode) Creates and installs a
ResettableClassFileTransformer
that implements the configuration of this agent builder with a givenInstrumentation
. If retransformation is enabled, the installation also causes all loaded types to be retransformed which have changed compared to the previous class file transformer that is provided as an argument.In order to assure the correct handling of the
AgentBuilder.InstallationListener
, an uninstallation should be applied via theResettableClassFileTransformer
'sreset
methods.- Specified by:
patchOn
in interfaceAgentBuilder
- Parameters:
instrumentation
- The instrumentation on which this agent builder's configuration is to be installed.classFileTransformer
- The class file transformer that is being patched.differentialMatcher
- The differential matcher to decide what types need retransformation.patchMode
- The patch mode to apply.- Returns:
- The installed class file transformer.
-
patchOnByteBuddyAgent
public ResettableClassFileTransformer patchOnByteBuddyAgent(ResettableClassFileTransformer classFileTransformer) Creates and installs a
ResettableClassFileTransformer
that implements the configuration of this agent builder with the Byte Buddy-agent which must be installed prior to calling this method. If retransformation is enabled, the installation also causes all loaded types to be retransformed which have changed compared to the previous class file transformer that is provided as an argument. Without specification,AgentBuilder.PatchMode.OVERLAP
is used.In order to assure the correct handling of the
AgentBuilder.InstallationListener
, an uninstallation should be applied via theResettableClassFileTransformer
'sreset
methods.- Specified by:
patchOnByteBuddyAgent
in interfaceAgentBuilder
- Parameters:
classFileTransformer
- The class file transformer that is being patched.- Returns:
- The installed class file transformer.
- See Also:
-
patchOnByteBuddyAgent
public ResettableClassFileTransformer patchOnByteBuddyAgent(ResettableClassFileTransformer classFileTransformer, AgentBuilder.PatchMode patchMode) Creates and installs a
ResettableClassFileTransformer
that implements the configuration of this agent builder with the Byte Buddy-agent which must be installed prior to calling this method. If retransformation is enabled, the installation also causes all loaded types to be retransformed which have changed compared to the previous class file transformer that is provided as an argument.In order to assure the correct handling of the
AgentBuilder.InstallationListener
, an uninstallation should be applied via theResettableClassFileTransformer
'sreset
methods.- Specified by:
patchOnByteBuddyAgent
in interfaceAgentBuilder
- Parameters:
classFileTransformer
- The class file transformer that is being patched.patchMode
- The patch mode to apply.- Returns:
- The installed class file transformer.
- See Also:
-