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.
Modifier and Type | Interface and Description |
---|---|
static interface |
AgentBuilder.BinaryLocator
A binary locator allows to specify how binary data is located by an
AgentBuilder . |
static class |
AgentBuilder.Default
The default implementation of an
AgentBuilder . |
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 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.Matchable<T extends AgentBuilder.Matchable<T>>
An abstraction for extending a matcher.
|
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 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 |
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(File folder,
Instrumentation instrumentation)
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.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.
|
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. |
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 |
with(AccessControlContext accessControlContext)
Defines classes to be loaded using the given access control context.
|
AgentBuilder |
with(AgentBuilder.BinaryLocator binaryLocator)
Defines the use of the given binary locator for locating binary data to given class names.
|
AgentBuilder |
with(AgentBuilder.InitializationStrategy initializationStrategy)
Defines a given initialization strategy to be applied to generated types.
|
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.RedefinitionStrategy redefinitionStrategy)
Specifies a strategy for modifying existing types.
|
AgentBuilder |
with(AgentBuilder.TypeStrategy typeStrategy)
Defines the use of the given definition handler that determines if a type should be rebased or redefined.
|
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.BinaryLocator binaryLocator)
binaryLocator
- The binary locator to use.AgentBuilder with(AgentBuilder.TypeStrategy typeStrategy)
typeStrategy
- The definition handler to use.AgentBuilder with(AccessControlContext accessControlContext)
accessControlContext
- The access control context to be used for loading classes.AgentBuilder with(AgentBuilder.InitializationStrategy initializationStrategy)
initializationStrategy
- The initialization strategy to use.AgentBuilder with(AgentBuilder.RedefinitionStrategy redefinitionStrategy)
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 enableBootstrapInjection(File folder, Instrumentation instrumentation)
folder
- The folder in which jar files of the injected classes are to be stored.instrumentation
- The instrumentation instance that is used for appending jar files to the
bootstrap class path.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_DECLARED_ONLY
as well as configuring the underlying ByteBuddy
instance to use a Implementation.Context.Disabled
.
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.
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.
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(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 and accepts all class loaders.
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!
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 and accepts all class loaders.
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!
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(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 and accepts all class loaders.
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!
rawMatcher
- A raw matcher that identifies types that should not be instrumented.ClassFileTransformer makeRaw()
ClassFileTransformer
that implements the configuration of this
agent builder.ClassFileTransformer installOn(Instrumentation instrumentation)
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.instrumentation
- The instrumentation on which this agent builder's configuration is to be installed.ClassFileTransformer installOnByteBuddyAgent()
ClassFileTransformer
that implements the configuration of
this agent builder with the Byte Buddy-agent which must be installed prior to calling this method.Copyright © 2014–2016. All rights reserved.