public static class AgentBuilder.Default extends Object implements AgentBuilder
The default implementation of an AgentBuilder
.
By default, Byte Buddy ignores any types loaded by the bootstrap class loader and
any synthetic type. Self-injection and rebasing is enabled. In order to avoid class format changes, set
AgentBuilder.disableBootstrapInjection()
). All types are parsed without their debugging information (AgentBuilder.TypeLocator.Default.FAST
).
Modifier and Type | Class and Description |
---|---|
protected static interface |
AgentBuilder.Default.BootstrapInjectionStrategy
An injection strategy for injecting classes into the bootstrap class loader.
|
protected class |
AgentBuilder.Default.Delegator<T extends AgentBuilder.Matchable<T>>
An abstract implementation of an agent builder that delegates all invocation to another instance.
|
protected static class |
AgentBuilder.Default.ExecutingTransformer
A
ClassFileTransformer that implements the enclosing agent builder's
configuration. |
protected class |
AgentBuilder.Default.Ignoring
A delegator transformer for further precising what types to ignore.
|
protected static interface |
AgentBuilder.Default.NativeMethodStrategy
A strategy for determining if a native method name prefix should be used when rebasing methods.
|
protected static interface |
AgentBuilder.Default.Transformation
A transformation serves as a handler for modifying a class.
|
protected class |
AgentBuilder.Default.Transforming
A helper class that describes a
AgentBuilder.Default after supplying
a AgentBuilder.RawMatcher such that one or several
AgentBuilder.Transformer s can be supplied. |
AgentBuilder.Default, AgentBuilder.DescriptionStrategy, AgentBuilder.Identified, AgentBuilder.Ignored, AgentBuilder.InitializationStrategy, AgentBuilder.InstallationStrategy, AgentBuilder.LambdaInstrumentationStrategy, AgentBuilder.Listener, AgentBuilder.LocationStrategy, AgentBuilder.Matchable<T extends AgentBuilder.Matchable<T>>, AgentBuilder.RawMatcher, AgentBuilder.RedefinitionStrategy, AgentBuilder.Transformer, AgentBuilder.TypeLocator, AgentBuilder.TypeStrategy
Modifier | Constructor and Description |
---|---|
|
Default()
Creates a new default agent builder that uses a default
ByteBuddy instance for creating classes. |
|
Default(ByteBuddy byteBuddy)
Creates a new agent builder with default settings.
|
protected |
Default(ByteBuddy byteBuddy,
AgentBuilder.TypeLocator typeLocator,
AgentBuilder.TypeStrategy typeStrategy,
AgentBuilder.LocationStrategy locationStrategy,
AgentBuilder.Listener listener,
AgentBuilder.Default.NativeMethodStrategy nativeMethodStrategy,
AccessControlContext accessControlContext,
AgentBuilder.InitializationStrategy initializationStrategy,
AgentBuilder.RedefinitionStrategy redefinitionStrategy,
AgentBuilder.Default.BootstrapInjectionStrategy bootstrapInjectionStrategy,
AgentBuilder.LambdaInstrumentationStrategy lambdaInstrumentationStrategy,
AgentBuilder.DescriptionStrategy descriptionStrategy,
AgentBuilder.InstallationStrategy installationStrategy,
AgentBuilder.RawMatcher ignoredTypeMatcher,
AgentBuilder.Default.Transformation transformation)
Creates a new default agent builder.
|
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.
|
boolean |
equals(Object other) |
int |
hashCode() |
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.
|
ClassFileTransformer |
installOn(Instrumentation instrumentation)
Creates and installs a
ClassFileTransformer that implements the configuration of
this agent builder with a given Instrumentation . |
ClassFileTransformer |
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. |
ClassFileTransformer |
makeRaw()
Creates a
ClassFileTransformer that implements the configuration of this
agent builder. |
String |
toString() |
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(AccessControlContext accessControlContext)
Assures that critical actions are performed using the supplied access control context.
|
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.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.RedefinitionStrategy redefinitionStrategy)
Specifies a strategy for modifying types that were already loaded prior to the installation of this transformer.
|
AgentBuilder |
with(AgentBuilder.TypeLocator typeLocator)
Defines the use of the given type locator for locating a
TypeDescription for an instrumented type. |
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. |
public Default()
ByteBuddy
instance for creating classes.Default#Default(ByteBuddy)
public Default(ByteBuddy byteBuddy)
net.bytebuddy
package and any synthetic type. Self-injection and rebasing is enabled. In order to avoid class format
changes, set AgentBuilder.disableBootstrapInjection()
). All types are parsed without their debugging information
(AgentBuilder.TypeLocator.Default.FAST
).byteBuddy
- The Byte Buddy instance to be used.protected Default(ByteBuddy byteBuddy, AgentBuilder.TypeLocator typeLocator, AgentBuilder.TypeStrategy typeStrategy, AgentBuilder.LocationStrategy locationStrategy, AgentBuilder.Listener listener, AgentBuilder.Default.NativeMethodStrategy nativeMethodStrategy, AccessControlContext accessControlContext, AgentBuilder.InitializationStrategy initializationStrategy, AgentBuilder.RedefinitionStrategy redefinitionStrategy, AgentBuilder.Default.BootstrapInjectionStrategy bootstrapInjectionStrategy, AgentBuilder.LambdaInstrumentationStrategy lambdaInstrumentationStrategy, AgentBuilder.DescriptionStrategy descriptionStrategy, AgentBuilder.InstallationStrategy installationStrategy, AgentBuilder.RawMatcher ignoredTypeMatcher, AgentBuilder.Default.Transformation transformation)
byteBuddy
- The Byte Buddy instance to be used.typeLocator
- The type locator to use.typeStrategy
- The definition handler to use.locationStrategy
- The location strategy to use.listener
- The listener to notify on transformations.nativeMethodStrategy
- The native method strategy to apply.accessControlContext
- The access control context to use for loading classes.initializationStrategy
- The initialization strategy to use for transformed types.redefinitionStrategy
- The redefinition strategy to apply.bootstrapInjectionStrategy
- The injection strategy for injecting classes into the bootstrap class loader.lambdaInstrumentationStrategy
- A strategy to determine of the LambdaMetafactory
should be instrumented to allow for the
instrumentation of classes that represent lambda expressions.descriptionStrategy
- The description strategy for resolving type descriptions for types.installationStrategy
- The installation strategy to use.ignoredTypeMatcher
- Identifies types that should not be instrumented.transformation
- The transformation object for handling type transformations.public AgentBuilder with(ByteBuddy byteBuddy)
AgentBuilder
ByteBuddy
instance to be used by the created agent.with
in interface AgentBuilder
byteBuddy
- The Byte Buddy instance to be used.byteBuddy
instance.public AgentBuilder with(AgentBuilder.Listener listener)
AgentBuilder
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.with
in interface AgentBuilder
listener
- The listener to be notified.public AgentBuilder with(AgentBuilder.TypeStrategy typeStrategy)
AgentBuilder
with
in interface AgentBuilder
typeStrategy
- The type strategy to use.public AgentBuilder with(AgentBuilder.TypeLocator typeLocator)
AgentBuilder
TypeDescription
for an instrumented type.with
in interface AgentBuilder
typeLocator
- The type locator to use.public AgentBuilder with(AgentBuilder.LocationStrategy locationStrategy)
AgentBuilder
with
in interface AgentBuilder
locationStrategy
- The location strategy to use.public AgentBuilder enableNativeMethodPrefix(String prefix)
AgentBuilder
Instrumentation
.enableNativeMethodPrefix
in interface AgentBuilder
prefix
- The prefix to be used.public AgentBuilder disableNativeMethodPrefix()
AgentBuilder
disableNativeMethodPrefix
in interface AgentBuilder
public AgentBuilder with(AccessControlContext accessControlContext)
AgentBuilder
with
in interface AgentBuilder
accessControlContext
- The access control context to be used for performing security critical action.public AgentBuilder with(AgentBuilder.RedefinitionStrategy redefinitionStrategy)
AgentBuilder
with
in interface AgentBuilder
redefinitionStrategy
- The redefinition strategy to apply.public AgentBuilder with(AgentBuilder.InitializationStrategy initializationStrategy)
AgentBuilder
with
in interface AgentBuilder
initializationStrategy
- The initialization strategy to use.public AgentBuilder with(AgentBuilder.LambdaInstrumentationStrategy lambdaInstrumentationStrategy)
AgentBuilder
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.
with
in interface AgentBuilder
lambdaInstrumentationStrategy
- true
if this feature should be enabled.public AgentBuilder with(AgentBuilder.DescriptionStrategy descriptionStrategy)
AgentBuilder
TypeDescription
for any type handled by the created transformer.with
in interface AgentBuilder
descriptionStrategy
- The description strategy to use.public AgentBuilder with(AgentBuilder.InstallationStrategy installationStrategy)
AgentBuilder
with
in interface AgentBuilder
installationStrategy
- The installation strategy to be used.public AgentBuilder enableBootstrapInjection(Instrumentation instrumentation, File folder)
AgentBuilder
enableBootstrapInjection
in interface AgentBuilder
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.public AgentBuilder disableBootstrapInjection()
AgentBuilder
disableBootstrapInjection
in interface AgentBuilder
public AgentBuilder disableClassFormatChanges()
AgentBuilder
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_DECLARED_ONLY
as well as configuring the underlying ByteBuddy
instance to use a Implementation.Context.Disabled
.
disableClassFormatChanges
in interface AgentBuilder
public AgentBuilder assureReadEdgeTo(Instrumentation instrumentation, Class<?>... type)
AgentBuilder
assureReadEdgeTo
in interface AgentBuilder
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
public AgentBuilder assureReadEdgeTo(Instrumentation instrumentation, JavaModule... module)
AgentBuilder
assureReadEdgeTo
in interface AgentBuilder
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
public AgentBuilder assureReadEdgeTo(Instrumentation instrumentation, Collection<? extends JavaModule> modules)
AgentBuilder
assureReadEdgeTo
in interface AgentBuilder
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
public AgentBuilder assureReadEdgeFromAndTo(Instrumentation instrumentation, Class<?>... type)
AgentBuilder
assureReadEdgeFromAndTo
in interface AgentBuilder
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
public AgentBuilder assureReadEdgeFromAndTo(Instrumentation instrumentation, JavaModule... module)
AgentBuilder
assureReadEdgeFromAndTo
in interface AgentBuilder
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
public AgentBuilder assureReadEdgeFromAndTo(Instrumentation instrumentation, Collection<? extends JavaModule> modules)
AgentBuilder
assureReadEdgeFromAndTo
in interface AgentBuilder
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
public AgentBuilder.Identified.Narrowable type(AgentBuilder.RawMatcher matcher)
AgentBuilder
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 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.
type
in interface AgentBuilder
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.public AgentBuilder.Identified.Narrowable type(ElementMatcher<? super TypeDescription> typeMatcher)
AgentBuilder
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 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 using
AgentBuilder.type(ElementMatcher, ElementMatcher)
instead.
type
in interface AgentBuilder
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.public AgentBuilder.Identified.Narrowable type(ElementMatcher<? super TypeDescription> typeMatcher, ElementMatcher<? super ClassLoader> classLoaderMatcher)
AgentBuilder
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 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.
type
in interface AgentBuilder
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.public AgentBuilder.Identified.Narrowable type(ElementMatcher<? super TypeDescription> typeMatcher, ElementMatcher<? super ClassLoader> classLoaderMatcher, ElementMatcher<? super JavaModule> moduleMatcher)
AgentBuilder
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 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.
type
in interface AgentBuilder
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.public AgentBuilder.Ignored ignore(ElementMatcher<? super TypeDescription> typeMatcher)
AgentBuilder
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.
ignore
in interface AgentBuilder
typeMatcher
- A matcher that identifies types that should not be instrumented.public AgentBuilder.Ignored ignore(ElementMatcher<? super TypeDescription> typeMatcher, ElementMatcher<? super ClassLoader> classLoaderMatcher)
AgentBuilder
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.
ignore
in interface AgentBuilder
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.public AgentBuilder.Ignored ignore(ElementMatcher<? super TypeDescription> typeMatcher, ElementMatcher<? super ClassLoader> classLoaderMatcher, ElementMatcher<? super JavaModule> moduleMatcher)
AgentBuilder
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.
ignore
in interface AgentBuilder
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.public AgentBuilder.Ignored ignore(AgentBuilder.RawMatcher rawMatcher)
AgentBuilder
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.
ignore
in interface AgentBuilder
rawMatcher
- A raw matcher that identifies types that should not be instrumented.public ClassFileTransformer makeRaw()
AgentBuilder
ClassFileTransformer
that implements the configuration of this
agent builder.makeRaw
in interface AgentBuilder
public ClassFileTransformer installOn(Instrumentation instrumentation)
AgentBuilder
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.
installOn
in interface AgentBuilder
instrumentation
- The instrumentation on which this agent builder's configuration is to be installed.public ClassFileTransformer installOnByteBuddyAgent()
AgentBuilder
ClassFileTransformer
that implements the configuration of
this agent builder with the Byte Buddy-agent which must be installed prior to calling this method.installOnByteBuddyAgent
in interface AgentBuilder
AgentBuilder.installOn(Instrumentation)
Copyright © 2014–2016. All rights reserved.