public interface AgentBuilder
An agent builder provides a convenience API for defining a
Java agent. By default,
this transformation is applied by rebasing the type if not specified otherwise by setting a
AgentBuilder.TypeStrategy
.
When defining several AgentBuilder.Transformer
s, the agent builder always
applies the transformers that were supplied with the last applicable matcher. Therefore, more general transformers
should be defined first.
Note: Any transformation is performed using the AccessControlContext
of an agent's creator.
Important: Types that implement lambda expressions (functional interfaces) are not instrumented by default but
only when enabling the builder's AgentBuilder.LambdaInstrumentationStrategy
.
Modifier and Type | Interface and Description |
---|---|
static interface |
AgentBuilder.CircularityLock
A circularity lock is responsible for preventing that a
ClassFileLocator is used recursively. |
static class |
AgentBuilder.Default
The default implementation of an
AgentBuilder . |
static interface |
AgentBuilder.DescriptionStrategy
A description strategy is responsible for resolving a
TypeDescription when transforming or retransforming/-defining a type. |
static interface |
AgentBuilder.FallbackStrategy
A fallback strategy allows to reattempt a transformation or a consideration for redefinition/retransformation in case an exception
occurs.
|
static interface |
AgentBuilder.Identified
Describes an
AgentBuilder which was handed a matcher for identifying
types to instrumented in order to supply one or several
AgentBuilder.Transformer s. |
static interface |
AgentBuilder.Ignored
Allows to further specify ignored types.
|
static interface |
AgentBuilder.InitializationStrategy
An initialization strategy which determines the handling of
LoadedTypeInitializer s
and the loading of auxiliary types. |
static interface |
AgentBuilder.InstallationStrategy
An installation strategy determines the reaction to a raised exception after the registration of a
ClassFileTransformer . |
static class |
AgentBuilder.LambdaInstrumentationStrategy
Implements the instrumentation of the
LambdaMetafactory if this feature is enabled. |
static interface |
AgentBuilder.Listener
A listener that is informed about events that occur during an instrumentation process.
|
static interface |
AgentBuilder.LocationStrategy
A strategy for creating a
ClassFileLocator when instrumenting a type. |
static interface |
AgentBuilder.Matchable<T extends AgentBuilder.Matchable<T>>
An abstraction for extending a matcher.
|
static interface |
AgentBuilder.PoolStrategy
A type locator allows to specify how
TypeDescription s are resolved by an AgentBuilder . |
static interface |
AgentBuilder.RawMatcher
A matcher that allows to determine if a
AgentBuilder.Transformer
should be applied during the execution of a ClassFileTransformer that was
generated by an AgentBuilder . |
static interface |
AgentBuilder.RedefinitionListenable
An agent builder configuration that allows the registration of listeners to the redefinition process.
|
static class |
AgentBuilder.RedefinitionStrategy
A redefinition strategy regulates how already loaded classes are modified by a built agent.
|
static interface |
AgentBuilder.Transformer
A transformer allows to apply modifications to a
DynamicType . |
static interface |
AgentBuilder.TypeStrategy
A type strategy is responsible for creating a type builder for a type that is being instrumented.
|
Modifier and Type | Method and Description |
---|---|
AgentBuilder |
assureReadEdgeFromAndTo(Instrumentation instrumentation,
Class<?>... type)
Assures that all modules of the supplied types are read by the module of any instrumented type and vice versa.
|
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.
|
AgentBuilder |
assureReadEdgeFromAndTo(Instrumentation instrumentation,
JavaModule... module)
Assures that all supplied modules are read by the module of any instrumented type and vice versa.
|
AgentBuilder |
assureReadEdgeTo(Instrumentation instrumentation,
Class<?>... type)
Assures that all modules of the supplied types are read by the module of any instrumented type.
|
AgentBuilder |
assureReadEdgeTo(Instrumentation instrumentation,
Collection<? extends JavaModule> modules)
Assures that all supplied modules are read by the module of any instrumented type.
|
AgentBuilder |
assureReadEdgeTo(Instrumentation instrumentation,
JavaModule... module)
Assures that all supplied modules are read by the module of any instrumented type.
|
AgentBuilder |
disableBootstrapInjection()
Disables injection of auxiliary classes into the bootstrap class path.
|
AgentBuilder |
disableClassFormatChanges()
Disables all implicit changes on a class file that Byte Buddy would apply for certain instrumentations.
|
AgentBuilder |
disableNativeMethodPrefix()
Disables the use of a native method prefix for instrumented methods.
|
AgentBuilder |
enableBootstrapInjection(Instrumentation instrumentation,
File folder)
Enables class injection of auxiliary classes into the bootstrap class loader.
|
AgentBuilder |
enableNativeMethodPrefix(String prefix)
Enables the use of the given native method prefix for instrumented methods.
|
AgentBuilder |
enableUnsafeBootstrapInjection()
Enables class injection of auxiliary classes into the bootstrap class loader which relies on
sun.misc.Unsafe . |
AgentBuilder.Ignored |
ignore(AgentBuilder.RawMatcher rawMatcher)
Excludes any type that is matched by the raw matcher provided to this method.
|
AgentBuilder.Ignored |
ignore(ElementMatcher<? super TypeDescription> typeMatcher)
Excludes any type that is matched by the provided matcher from instrumentation and considers types by all
ClassLoader s. |
AgentBuilder.Ignored |
ignore(ElementMatcher<? super TypeDescription> typeMatcher,
ElementMatcher<? super ClassLoader> classLoaderMatcher)
Excludes any type that is matched by the provided matcher and is loaded by a class loader matching the second matcher.
|
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.
|
ResettableClassFileTransformer |
installOn(Instrumentation instrumentation)
Creates and installs a
ClassFileTransformer that implements the configuration of
this agent builder with a given Instrumentation . |
ResettableClassFileTransformer |
installOnByteBuddyAgent()
Creates and installs a
ClassFileTransformer that implements the configuration of
this agent builder with the Byte Buddy-agent which must be installed prior to calling this method. |
ResettableClassFileTransformer |
makeRaw()
Creates a
ClassFileTransformer that implements the configuration of this
agent builder. |
AgentBuilder.Identified.Narrowable |
type(AgentBuilder.RawMatcher matcher)
Matches a type being loaded in order to apply the supplied
AgentBuilder.Transformer s before loading this type. |
AgentBuilder.Identified.Narrowable |
type(ElementMatcher<? super TypeDescription> typeMatcher)
Matches a type being loaded in order to apply the supplied
AgentBuilder.Transformer s before loading this type. |
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. |
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. |
AgentBuilder |
with(AgentBuilder.CircularityLock circularityLock)
Defines a circularity lock that is acquired upon executing code that potentially loads new classes.
|
AgentBuilder |
with(AgentBuilder.DescriptionStrategy descriptionStrategy)
Specifies a strategy to be used for resolving
TypeDescription for any type handled by the created transformer. |
AgentBuilder |
with(AgentBuilder.FallbackStrategy fallbackStrategy)
Specifies a fallback strategy to that this agent builder applies upon installing an agent and during class file transformation.
|
AgentBuilder |
with(AgentBuilder.InitializationStrategy initializationStrategy)
Defines a given initialization strategy to be applied to generated types.
|
AgentBuilder |
with(AgentBuilder.InstallationStrategy installationStrategy)
Specifies an installation strategy that this agent builder applies upon installing an agent.
|
AgentBuilder |
with(AgentBuilder.LambdaInstrumentationStrategy lambdaInstrumentationStrategy)
Enables or disables management of the JVM's
LambdaMetafactory which is responsible for creating classes that
implement lambda expressions. |
AgentBuilder |
with(AgentBuilder.Listener listener)
Defines the given
AgentBuilder.Listener to be notified by the created agent. |
AgentBuilder |
with(AgentBuilder.LocationStrategy locationStrategy)
Defines the use of the given location strategy for locating binary data to given class names.
|
AgentBuilder |
with(AgentBuilder.PoolStrategy poolStrategy)
Defines the use of the given type locator for locating a
TypeDescription for an instrumented type. |
AgentBuilder.RedefinitionListenable.WithoutBatchStrategy |
with(AgentBuilder.RedefinitionStrategy redefinitionStrategy)
Specifies a strategy for modifying types that were already loaded prior to the installation of this transformer.
|
AgentBuilder |
with(AgentBuilder.TypeStrategy typeStrategy)
Defines how types should be transformed, e.g. if they should be rebased or redefined by the created agent.
|
AgentBuilder |
with(ByteBuddy byteBuddy)
Defines the given
ByteBuddy instance to be used by the created agent. |
AgentBuilder with(ByteBuddy byteBuddy)
ByteBuddy
instance to be used by the created agent.byteBuddy
- The Byte Buddy instance to be used.byteBuddy
instance.AgentBuilder with(AgentBuilder.Listener listener)
AgentBuilder.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.listener
- The listener to be notified.AgentBuilder with(AgentBuilder.CircularityLock circularityLock)
AgentBuilder.CircularityLock
to avoid that any classes that are required to execute an agent
causes a ClassCircularityError
.circularityLock
- The circularity lock to use.AgentBuilder with(AgentBuilder.PoolStrategy poolStrategy)
TypeDescription
for an instrumented type.poolStrategy
- The type locator to use.AgentBuilder with(AgentBuilder.LocationStrategy locationStrategy)
locationStrategy
- The location strategy to use.AgentBuilder with(AgentBuilder.TypeStrategy typeStrategy)
typeStrategy
- The type strategy to use.AgentBuilder with(AgentBuilder.InitializationStrategy initializationStrategy)
initializationStrategy
- The initialization strategy to use.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
disableClassFormatChanges()
.
redefinitionStrategy
- The redefinition strategy to apply.AgentBuilder with(AgentBuilder.LambdaInstrumentationStrategy lambdaInstrumentationStrategy)
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 invoke
AgentBuilder.LambdaInstrumentationStrategy.release(ClassFileTransformer, Instrumentation)
. Otherwise, the executing VMs class
loader retains a reference to the class file transformer what can cause a memory leak.
lambdaInstrumentationStrategy
- true
if this feature should be enabled.AgentBuilder with(AgentBuilder.DescriptionStrategy descriptionStrategy)
TypeDescription
for any type handled by the created transformer.descriptionStrategy
- The description strategy to use.AgentBuilder with(AgentBuilder.InstallationStrategy installationStrategy)
installationStrategy
- The installation strategy to be used.AgentBuilder with(AgentBuilder.FallbackStrategy fallbackStrategy)
fallbackStrategy
- The fallback strategy to be used.AgentBuilder enableBootstrapInjection(Instrumentation instrumentation, File folder)
instrumentation
- The instrumentation instance that is used for appending jar files to the
bootstrap class path.folder
- The folder in which jar files of the injected classes are to be stored.AgentBuilder enableUnsafeBootstrapInjection()
sun.misc.Unsafe
.AgentBuilder enableNativeMethodPrefix(String prefix)
Instrumentation
.prefix
- The prefix to be used.AgentBuilder disableNativeMethodPrefix()
AgentBuilder disableBootstrapInjection()
AgentBuilder 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
and AgentBuilder.TypeStrategy.Default.REDEFINE_FROZEN
as well as configuring the underlying ByteBuddy
instance to use a Implementation.Context.Disabled
.
Using this strategy also configures Byte Buddy to create frozen instrumented types and discards any explicit configuration.
AgentBuilder assureReadEdgeTo(Instrumentation instrumentation, Class<?>... type)
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.AgentBuilder.Listener.ModuleReadEdgeCompleting
AgentBuilder assureReadEdgeTo(Instrumentation instrumentation, JavaModule... module)
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.AgentBuilder.Listener.ModuleReadEdgeCompleting
AgentBuilder assureReadEdgeTo(Instrumentation instrumentation, Collection<? extends JavaModule> modules)
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.AgentBuilder.Listener.ModuleReadEdgeCompleting
AgentBuilder assureReadEdgeFromAndTo(Instrumentation instrumentation, Class<?>... type)
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.AgentBuilder.Listener.ModuleReadEdgeCompleting
AgentBuilder assureReadEdgeFromAndTo(Instrumentation instrumentation, JavaModule... module)
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.AgentBuilder.Listener.ModuleReadEdgeCompleting
AgentBuilder assureReadEdgeFromAndTo(Instrumentation instrumentation, Collection<? extends JavaModule> modules)
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.AgentBuilder.Listener.ModuleReadEdgeCompleting
AgentBuilder.Identified.Narrowable type(ElementMatcher<? super TypeDescription> typeMatcher)
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, this matcher is always executed first whereas the following matchers are
executed in the order of their execution. If any matcher indicates that a type is to be matched, none of the following matchers is still queried.
This behavior can be changed by AgentBuilder.Identified.Extendable.asDecorator()
where subsequent type matchers are also applied.
Note: When applying a matcher, regard the performance implications by 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 using
type(ElementMatcher, ElementMatcher)
instead.
typeMatcher
- An ElementMatcher
that is applied on the type being loaded that
decides if the entailed AgentBuilder.Transformer
s should
be applied for that type.AgentBuilder.Transformer
s to be applied when the given typeMatcher
indicates a match.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, this matcher is always executed first whereas the following matchers are
executed in the order of their execution. If any matcher indicates that a type is to be matched, none of the following matchers is still queried.
This behavior can be changed by AgentBuilder.Identified.Extendable.asDecorator()
where subsequent type matchers are also applied.
Note: When applying a matcher, regard the performance implications by 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.
typeMatcher
- An ElementMatcher
that is applied on the type being
loaded that decides if the entailed
AgentBuilder.Transformer
s should be applied for
that type.classLoaderMatcher
- An ElementMatcher
that is applied to the
ClassLoader
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.AgentBuilder.Transformer
s to be applied when both the given
typeMatcher
and classLoaderMatcher
indicate a match.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, this matcher is always executed first whereas the following matchers are
executed in the order of their execution. If any matcher indicates that a type is to be matched, none of the following matchers is still queried.
This behavior can be changed by AgentBuilder.Identified.Extendable.asDecorator()
where subsequent type matchers are also applied.
Note: When applying a matcher, regard the performance implications by 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.
typeMatcher
- An ElementMatcher
that is applied on the type being
loaded that decides if the entailed
AgentBuilder.Transformer
s should be applied for
that type.classLoaderMatcher
- An ElementMatcher
that is applied to the
ClassLoader
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
- An ElementMatcher
that is applied to the JavaModule
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.AgentBuilder.Transformer
s to be applied when both the given
typeMatcher
and classLoaderMatcher
indicate a match.AgentBuilder.Identified.Narrowable type(AgentBuilder.RawMatcher matcher)
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, this matcher is always executed first whereas the following matchers are executed in the order of their execution. If any matcher indicates that a type is to be matched, none of the following matchers is still queried.
Note: When applying a matcher, regard the performance implications by 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.
matcher
- A matcher that decides if the entailed AgentBuilder.Transformer
s should be
applied for a type that is being loaded.AgentBuilder.Transformer
s to be applied when the given matcher
indicates a match.AgentBuilder.Ignored ignore(ElementMatcher<? super TypeDescription> typeMatcher)
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 a AgentBuilder.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.
typeMatcher
- A matcher that identifies types that should not be instrumented.AgentBuilder.Ignored ignore(ElementMatcher<? super TypeDescription> typeMatcher, ElementMatcher<? super ClassLoader> classLoaderMatcher)
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 a AgentBuilder.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.
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.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 a AgentBuilder.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.
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.AgentBuilder.Ignored ignore(AgentBuilder.RawMatcher rawMatcher)
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 a AgentBuilder.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.
rawMatcher
- A raw matcher that identifies types that should not be instrumented.ResettableClassFileTransformer makeRaw()
ClassFileTransformer
that implements the configuration of this
agent builder.ResettableClassFileTransformer installOn(Instrumentation instrumentation)
Creates and installs a ClassFileTransformer
that implements the configuration of
this agent builder with a given Instrumentation
. If retransformation is enabled,
the installation also causes all loaded types to be retransformed.
If installing the created class file transformer causes an exception to be thrown, the consequences of this
exception are determined by the AgentBuilder.InstallationStrategy
of this builder.
instrumentation
- The instrumentation on which this agent builder's configuration is to be installed.ResettableClassFileTransformer installOnByteBuddyAgent()
ClassFileTransformer
that implements the configuration of
this agent builder with the Byte Buddy-agent which must be installed prior to calling this method.installOn(Instrumentation)
Copyright © 2014–2017. All rights reserved.