Class ByteBuddy
- Subclassing some type: A subclass - as the name suggests - extends another, existing Java type. Virtual members of the generated type's super types can be overridden. Subclasses can also be interface extensions of one or several interfaces.
- Redefining a type: By redefining a type, it is not only possible to override virtual methods of the redefined type but also to redefine existing methods. This way, it is also possible to change the behavior of non-virtual methods and constructors of the redefined type.
- Rebasing a type: Rebasing a type works similar to creating a subclass, i.e. any method being overridden is still capable of invoking any original code of the rebased type. Any rebased method is however inlined into the rebased type and any original code is preserved automatically. This way, the type's identity does not change.
DynamicType.Builder
interface. Byte Buddy's API is expressed by fully immutable
components and is therefore thread-safe. As a consequence, method calls must be chained for all of Byte Buddy's
component, e.g. a method call like the following has no effect:
ByteBuddy byteBuddy = new ByteBuddy(); byteBuddy.foo()Instead, the following method chain is correct use of the API:
ByteBuddy byteBuddy = new ByteBuddy().foo();
For the creation of Java agents, Byte Buddy offers a convenience API implemented by the
AgentBuilder
. The API wraps a ByteBuddy
instance and offers agent-specific
configuration opportunities by integrating against the Instrumentation
API.
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprotected static class
An implementation fo thevalues
method of an enumeration type.protected static enum
A constructor strategy for implementing a Java record.protected static enum
Implements the object methods of the Java record type. -
Field Summary
FieldsModifier and TypeFieldDescriptionprotected final AnnotationRetention
The annotation retention strategy to use.protected final AnnotationValueFilter.Factory
The annotation value filter factory to use.protected final AuxiliaryType.NamingStrategy
The naming strategy to use for naming auxiliary types.private static final String
The default name of a fixed context name for synthetic fields and methods.private static final String
The default prefix for the defaultNamingStrategy
.private static final String
The default suffix when defining aAuxiliaryType.NamingStrategy
.protected final ClassFileVersion
The class file version to use for types that are not based on an existing class file.protected final ClassWriterStrategy
The class writer strategy to use.private static final AuxiliaryType.NamingStrategy
The default auxiliary naming strategy ornull
if no such strategy is set.private static final Implementation.Context.Factory
The default implementation context factory ornull
if no such factory is set.static final String
A property that controls the default naming strategy.private static final NamingStrategy
The default naming strategy ornull
if no such strategy is set.protected final LatentMatcher<? super MethodDescription>
A matcher for identifying methods that should be excluded from instrumentation.protected final Implementation.Context.Factory
The implementation context factory to use.protected final InstrumentedType.Factory
The instrumented type factory to use.protected final MethodGraph.Compiler
The method graph compiler to use.protected final NamingStrategy
The naming strategy to use.protected final TypeValidation
Determines if a type should be explicitly validated.protected final VisibilityBridgeStrategy
The visibility bridge strategy to apply. -
Constructor Summary
ConstructorsModifierConstructorDescriptionCreates a new Byte Buddy instance with a default configuration that is suitable for most use cases.ByteBuddy
(ClassFileVersion classFileVersion) Creates a new Byte Buddy instance with a default configuration that is suitable for most use cases.protected
ByteBuddy
(ClassFileVersion classFileVersion, NamingStrategy namingStrategy, AuxiliaryType.NamingStrategy auxiliaryTypeNamingStrategy, AnnotationValueFilter.Factory annotationValueFilterFactory, AnnotationRetention annotationRetention, Implementation.Context.Factory implementationContextFactory, MethodGraph.Compiler methodGraphCompiler, InstrumentedType.Factory instrumentedTypeFactory, TypeValidation typeValidation, VisibilityBridgeStrategy visibilityBridgeStrategy, ClassWriterStrategy classWriterStrategy, LatentMatcher<? super MethodDescription> ignoredMethods) Creates a new Byte Buddy instance. -
Method Summary
Modifier and TypeMethodDescription<T> DynamicType.Builder<T>
Decorates a type withAsmVisitorWrapper
and allows adding attributes and annotations.<T> DynamicType.Builder<T>
decorate
(Class<T> type, ClassFileLocator classFileLocator) Decorates a type withAsmVisitorWrapper
and allows adding attributes and annotations.<T> DynamicType.Builder<T>
decorate
(TypeDescription type, ClassFileLocator classFileLocator) Decorates a type withAsmVisitorWrapper
and allows adding attributes and annotations.private static <T> T
doPrivileged
(PrivilegedAction<T> action) A proxy forjava.security.AccessController#doPrivileged
that is activated if available.ignore
(ElementMatcher<? super MethodDescription> ignoredMethods) Creates a new configuration where anyMethodDescription
that matches the provided method matcher is excluded from instrumentation.ignore
(LatentMatcher<? super MethodDescription> ignoredMethods) Creates a new configuration where anyMethodDescription
that matches the provided method matcher is excluded from instrumentation.DynamicType.Builder<? extends Annotation>
Creates a newAnnotation
type.DynamicType.Builder<? extends Enum<?>>
makeEnumeration
(String... value) Creates a newEnum
type.DynamicType.Builder<? extends Enum<?>>
makeEnumeration
(Collection<? extends String> values) Creates a newEnum
type.Creates a new, plain interface type.<T> DynamicType.Builder<T>
makeInterface
(Class<T> interfaceType) Creates a new interface type that extends the provided interface.makeInterface
(Type... interfaceType) Creates a new interface type that extends the provided interface.makeInterface
(Collection<? extends TypeDefinition> interfaceTypes) Creates a new interface type that extends the provided interface.makeInterface
(List<? extends Type> interfaceTypes) Creates a new interface type that extends the provided interface.makeInterface
(TypeDefinition... interfaceType) Creates a new interface type that extends the provided interface.makePackage
(String name) Creates a new package definition.Creates a new Java record.<T> DynamicType.Builder<T>
Rebases the given type where any intercepted method that is declared by the redefined type is preserved within the rebased type's class such that the class's original can be invoked from the new method implementations.<T> DynamicType.Builder<T>
rebase
(Class<T> type, ClassFileLocator classFileLocator) Rebases the given type where any intercepted method that is declared by the redefined type is preserved within the rebased type's class such that the class's original can be invoked from the new method implementations.<T> DynamicType.Builder<T>
rebase
(Class<T> type, ClassFileLocator classFileLocator, MethodNameTransformer methodNameTransformer) Rebases the given type where any intercepted method that is declared by the redefined type is preserved within the rebased type's class such that the class's original can be invoked from the new method implementations.rebase
(Package aPackage, ClassFileLocator classFileLocator) Rebases a package.rebase
(PackageDescription aPackage, ClassFileLocator classFileLocator) Rebases a package.<T> DynamicType.Builder<T>
rebase
(TypeDescription type, ClassFileLocator classFileLocator) Rebases the given type where any intercepted method that is declared by the redefined type is preserved within the rebased type's class such that the class's original can be invoked from the new method implementations.<T> DynamicType.Builder<T>
rebase
(TypeDescription type, ClassFileLocator classFileLocator, MethodNameTransformer methodNameTransformer) Rebases the given type where any intercepted method that is declared by the redefined type is preserved within the rebased type's class such that the class's original can be invoked from the new method implementations.<T> DynamicType.Builder<T>
Redefines the given type where any intercepted method that is declared by the redefined type is fully replaced by the new implementation.<T> DynamicType.Builder<T>
redefine
(Class<T> type, ClassFileLocator classFileLocator) Redefines the given type where any intercepted method that is declared by the redefined type is fully replaced by the new implementation.<T> DynamicType.Builder<T>
redefine
(TypeDescription type, ClassFileLocator classFileLocator) Redefines the given type where any intercepted method that is declared by the redefined type is fully replaced by the new implementation.<T> DynamicType.Builder<T>
Creates a new builder for subclassing the provided type.<T> DynamicType.Builder<T>
subclass
(Class<T> superType, ConstructorStrategy constructorStrategy) Creates a new builder for subclassing the provided type.Creates a new builder for subclassing the provided type.subclass
(Type superType, ConstructorStrategy constructorStrategy) Creates a new builder for subclassing the provided type.subclass
(TypeDefinition superType) Creates a new builder for subclassing the provided type.subclass
(TypeDefinition superType, ConstructorStrategy constructorStrategy) Creates a new builder for subclassing the provided type.with
(ClassFileVersion classFileVersion) Creates a new configuration where all class files that are not based on an existing class file are created using the supplied class file version.with
(ClassWriterStrategy classWriterStrategy) Creates a new configuration that applies the supplied class writer strategy.with
(InstrumentedType.Factory instrumentedTypeFactory) Configures Byte Buddy to use the specified factory for creatingInstrumentedType
s.with
(MethodGraph.Compiler methodGraphCompiler) Creates a new configuration where theMethodGraph.Compiler
is used for creating aMethodGraph
of the instrumented type.with
(TypeValidation typeValidation) Creates a new configuration that applies the supplied type validation.with
(VisibilityBridgeStrategy visibilityBridgeStrategy) Creates a new configuration that applies the supplied visibility bridge strategy.with
(AnnotationRetention annotationRetention) Creates a new configuration where annotations that are found in an existing class file are or are not preserved in the format they are discovered, i.e.with
(AnnotationValueFilter.Factory annotationValueFilterFactory) Creates a new configuration where annotation values are written according to the given filter factory.with
(AuxiliaryType.NamingStrategy auxiliaryTypeNamingStrategy) Creates a new configuration where auxiliary types are named by applying the given naming strategy.with
(Implementation.Context.Factory implementationContextFactory) Creates a new configuration where theImplementation.Context
of any created type is a product of the given implementation context factory.with
(NamingStrategy namingStrategy) Creates a new configuration where new types are named by applying the given naming strategy.
-
Field Details
-
DEFAULT_NAMING_PROPERTY
A property that controls the default naming strategy. If not set, Byte Buddy is generating random names for types that are not named explicitly. If set tofixed
, Byte Buddy is setting names deterministically without any random element, or tocaller
, if a name should be fixed but contain the name of the caller class and method. If set to a numeric value, Byte Buddy is generating random names, using the number as a seed.- See Also:
-
BYTE_BUDDY_DEFAULT_PREFIX
The default prefix for the defaultNamingStrategy
.- See Also:
-
BYTE_BUDDY_DEFAULT_SUFFIX
The default suffix when defining aAuxiliaryType.NamingStrategy
.- See Also:
-
BYTE_BUDDY_DEFAULT_CONTEXT_NAME
The default name of a fixed context name for synthetic fields and methods.- See Also:
-
DEFAULT_NAMING_STRATEGY
The default naming strategy ornull
if no such strategy is set. -
DEFAULT_AUXILIARY_NAMING_STRATEGY
The default auxiliary naming strategy ornull
if no such strategy is set. -
DEFAULT_IMPLEMENTATION_CONTEXT_FACTORY
@MaybeNull private static final Implementation.Context.Factory DEFAULT_IMPLEMENTATION_CONTEXT_FACTORYThe default implementation context factory ornull
if no such factory is set. -
classFileVersion
The class file version to use for types that are not based on an existing class file. -
namingStrategy
The naming strategy to use. -
auxiliaryTypeNamingStrategy
The naming strategy to use for naming auxiliary types. -
annotationValueFilterFactory
The annotation value filter factory to use. -
annotationRetention
The annotation retention strategy to use. -
implementationContextFactory
The implementation context factory to use. -
methodGraphCompiler
The method graph compiler to use. -
instrumentedTypeFactory
The instrumented type factory to use. -
ignoredMethods
A matcher for identifying methods that should be excluded from instrumentation. -
typeValidation
Determines if a type should be explicitly validated. -
visibilityBridgeStrategy
The visibility bridge strategy to apply. -
classWriterStrategy
The class writer strategy to use.
-
-
Constructor Details
-
ByteBuddy
public ByteBuddy()Creates a new Byte Buddy instance with a default configuration that is suitable for most use cases.
When creating this configuration, Byte Buddy attempts to discover the current JVM's version. If this is not possible, class files are created Java 6-compatible.
-
ByteBuddy
Creates a new Byte Buddy instance with a default configuration that is suitable for most use cases.- Parameters:
classFileVersion
- The class file version to use for types that are not based on an existing class file.
-
ByteBuddy
protected ByteBuddy(ClassFileVersion classFileVersion, NamingStrategy namingStrategy, AuxiliaryType.NamingStrategy auxiliaryTypeNamingStrategy, AnnotationValueFilter.Factory annotationValueFilterFactory, AnnotationRetention annotationRetention, Implementation.Context.Factory implementationContextFactory, MethodGraph.Compiler methodGraphCompiler, InstrumentedType.Factory instrumentedTypeFactory, TypeValidation typeValidation, VisibilityBridgeStrategy visibilityBridgeStrategy, ClassWriterStrategy classWriterStrategy, LatentMatcher<? super MethodDescription> ignoredMethods) Creates a new Byte Buddy instance.- Parameters:
classFileVersion
- The class file version to use for types that are not based on an existing class file.namingStrategy
- The naming strategy to use.auxiliaryTypeNamingStrategy
- The naming strategy to use for naming auxiliary types.annotationValueFilterFactory
- The annotation value filter factory to use.annotationRetention
- The annotation retention strategy to use.implementationContextFactory
- The implementation context factory to use.methodGraphCompiler
- The method graph compiler to use.instrumentedTypeFactory
- The instrumented type factory to use.typeValidation
- Determines if a type should be explicitly validated.visibilityBridgeStrategy
- The visibility bridge strategy to apply.classWriterStrategy
- The class writer strategy to use.ignoredMethods
- A matcher for identifying methods that should be excluded from instrumentation.
-
-
Method Details
-
doPrivileged
A proxy forjava.security.AccessController#doPrivileged
that is activated if available.- Type Parameters:
T
- The type of the action's resolved value.- Parameters:
action
- The action to execute from a privileged context.- Returns:
- The action's resolved value.
-
subclass
Creates a new builder for subclassing the provided type. If the provided type is an interface, a new class implementing this interface type is created.
When extending a class, Byte Buddy imitates all visible constructors of the subclassed type. Any constructor is implemented to only invoke its super type constructor of equal signature. Another behavior can be specified by supplying an explicit
ConstructorStrategy
bysubclass(Class, ConstructorStrategy)
.Note: This methods implements the supplied types in a generified state if they declare type variables or an owner type.
Note: Byte Buddy does not cache previous subclasses but will attempt the generation of a new subclass. For caching types, a external cache or
TypeCache
should be used.- Type Parameters:
T
- A loaded type that the generated class is guaranteed to inherit.- Parameters:
superType
- The super class or interface type to extend.- Returns:
- A type builder for creating a new class extending the provided class or interface.
-
subclass
public <T> DynamicType.Builder<T> subclass(Class<T> superType, ConstructorStrategy constructorStrategy) Creates a new builder for subclassing the provided type. If the provided type is an interface, a new class implementing this interface type is created.
Note: This methods implements the supplied types in a generified state if they declare type variables or an owner type.
Note: Byte Buddy does not cache previous subclasses but will attempt the generation of a new subclass. For caching types, a external cache or
TypeCache
should be used.- Type Parameters:
T
- A loaded type that the generated class is guaranteed to inherit.- Parameters:
superType
- The super class or interface type to extend.constructorStrategy
- A constructor strategy that determines the- Returns:
- A type builder for creating a new class extending the provided class or interface.
-
subclass
Creates a new builder for subclassing the provided type. If the provided type is an interface, a new class implementing this interface type is created.
When extending a class, Byte Buddy imitates all visible constructors of the subclassed type. Any constructor is implemented to only invoke its super type constructor of equal signature. Another behavior can be specified by supplying an explicit
ConstructorStrategy
bysubclass(Type, ConstructorStrategy)
.Note: This methods implements the supplied types as is, i.e. any
Class
values are implemented as raw types if they declare type variables.Note: Byte Buddy does not cache previous subclasses but will attempt the generation of a new subclass. For caching types, a external cache or
TypeCache
should be used.- Parameters:
superType
- The super class or interface type to extend. The type must be a raw type or parameterized type. All type variables that are referenced by the generic type must be declared by the generated subclass before creating the type.- Returns:
- A type builder for creating a new class extending the provided class or interface.
-
subclass
Creates a new builder for subclassing the provided type. If the provided type is an interface, a new class implementing this interface type is created.
Note: This methods implements the supplied types as is, i.e. any
Class
values are implemented as raw types if they declare type variables.Note: Byte Buddy does not cache previous subclasses but will attempt the generation of a new subclass. For caching types, a external cache or
TypeCache
should be used.- Parameters:
superType
- The super class or interface type to extend. The type must be a raw type or parameterized type. All type variables that are referenced by the generic type must be declared by the generated subclass before creating the type.constructorStrategy
- A constructor strategy that determines the- Returns:
- A type builder for creating a new class extending the provided class or interface.
-
subclass
Creates a new builder for subclassing the provided type. If the provided type is an interface, a new class implementing this interface type is created.
When extending a class, Byte Buddy imitates all visible constructors of the subclassed type and sets them to be
public
. Any constructor is implemented to only invoke its super type constructor of equal signature. Another behavior can be specified by supplying an explicitConstructorStrategy
bysubclass(TypeDefinition, ConstructorStrategy)
.Note: This methods implements the supplied types as is, i.e. any
TypeDescription
values are implemented as raw types if they declare type variables.Note: Byte Buddy does not cache previous subclasses but will attempt the generation of a new subclass. For caching types, a external cache or
TypeCache
should be used.- Parameters:
superType
- The super class or interface type to extend. The type must be a raw type or parameterized type. All type variables that are referenced by the generic type must be declared by the generated subclass before creating the type.- Returns:
- A type builder for creating a new class extending the provided class or interface.
-
subclass
public DynamicType.Builder<?> subclass(TypeDefinition superType, ConstructorStrategy constructorStrategy) Creates a new builder for subclassing the provided type. If the provided type is an interface, a new class implementing this interface type is created.
Note: This methods implements the supplied types as is, i.e. any
TypeDescription
values are implemented as raw types if they declare type variables.Note: Byte Buddy does not cache previous subclasses but will attempt the generation of a new subclass. For caching types, a external cache or
TypeCache
should be used.- Parameters:
superType
- The super class or interface type to extend. The type must be a raw type or parameterized type. All type variables that are referenced by the generic type must be declared by the generated subclass before creating the type.constructorStrategy
- A constructor strategy that determines the- Returns:
- A type builder for creating a new class extending the provided class or interface.
-
makeInterface
Creates a new, plain interface type.
Note: Byte Buddy does not cache previous subclasses but will attempt the generation of a new subclass. For caching types, a external cache or
TypeCache
should be used.- Returns:
- A type builder that creates a new interface type.
-
makeInterface
Creates a new interface type that extends the provided interface.
Note: This methods implements the supplied types in a generified state if they declare type variables or an owner type.
Note: Byte Buddy does not cache previous subclasses but will attempt the generation of a new subclass. For caching types, a external cache or
TypeCache
should be used.- Type Parameters:
T
- A loaded type that the generated interface is guaranteed to inherit.- Parameters:
interfaceType
- An interface type that the generated interface implements.- Returns:
- A type builder that creates a new interface type.
-
makeInterface
Creates a new interface type that extends the provided interface.
Note: This methods implements the supplied types as is, i.e. any
Class
values are implemented as raw types if they declare type variables or an owner type.Note: Byte Buddy does not cache previous subclasses but will attempt the generation of a new subclass. For caching types, a external cache or
TypeCache
should be used.- Parameters:
interfaceType
- The interface types to implement. The types must be raw or parameterized types. All type variables that are referenced by a parameterized type must be declared by the generated subclass before creating the type.- Returns:
- A type builder that creates a new interface type.
-
makeInterface
Creates a new interface type that extends the provided interface.
Note: This methods implements the supplied types as is, i.e. any
Class
values are implemented as raw types if they declare type variables or an owner type.Note: Byte Buddy does not cache previous subclasses but will attempt the generation of a new subclass. For caching types, a external cache or
TypeCache
should be used.- Parameters:
interfaceTypes
- The interface types to implement. The types must be raw or parameterized types. All type variables that are referenced by a parameterized type must be declared by the generated subclass before creating the type.- Returns:
- A type builder that creates a new interface type.
-
makeInterface
Creates a new interface type that extends the provided interface.
Note: This methods implements the supplied types as is, i.e. any
TypeDescription
values are implemented as raw types if they declare type variables or an owner type.Note: Byte Buddy does not cache previous subclasses but will attempt the generation of a new subclass. For caching types, a external cache or
TypeCache
should be used.- Parameters:
interfaceType
- The interface types to implement. The types must be raw or parameterized types. All type variables that are referenced by a parameterized type must be declared by the generated subclass before creating the type.- Returns:
- A type builder that creates a new interface type.
-
makeInterface
Creates a new interface type that extends the provided interface.
Note: This methods implements the supplied types as is, i.e. any
TypeDescription
values are implemented as raw types if they declare type variables or an owner type.Note: Byte Buddy does not cache previous subclasses but will attempt the generation of a new subclass. For caching types, a external cache or
TypeCache
should be used.- Parameters:
interfaceTypes
- The interface types to implement. The types must be raw or parameterized types. All type variables that are referenced by a parameterized type must be declared by the generated subclass before creating the type.- Returns:
- A type builder that creates a new interface type.
-
makePackage
Creates a new package definition. Package definitions are defined by classes named
package-info
without any methods or fields but permit annotations. Any field or method definition will cause anIllegalStateException
to be thrown when the type is created.Note: Byte Buddy does not cache previous subclasses but will attempt the generation of a new subclass. For caching types, a external cache or
TypeCache
should be used.- Parameters:
name
- The fully qualified name of the package.- Returns:
- A type builder that creates a
package-info
class file.
-
makeRecord
Creates a new Java record. This builder automatically defines fields for record members, standard accessors and a record constructor for any defined record component.- Returns:
- A dynamic type builder that creates a record.
-
makeAnnotation
Creates a new
Annotation
type. Annotation properties are implemented as non-static, public methods with the property type being defined as the return type.Note: Byte Buddy does not cache previous subclasses but will attempt the generation of a new subclass. For caching types, a external cache or
TypeCache
should be used.- Returns:
- A type builder that creates a new
Annotation
type.
-
makeEnumeration
Creates a new
Enum
type.Note: Byte Buddy does not cache previous subclasses but will attempt the generation of a new subclass. For caching types, a external cache or
TypeCache
should be used.- Parameters:
value
- The names of the type's enumeration constants- Returns:
- A type builder for creating an enumeration type.
-
makeEnumeration
Creates a new
Enum
type.Note: Byte Buddy does not cache previous subclasses but will attempt the generation of a new subclass. For caching types, a external cache or
TypeCache
should be used.- Parameters:
values
- The names of the type's enumeration constants- Returns:
- A type builder for creating an enumeration type.
-
redefine
Redefines the given type where any intercepted method that is declared by the redefined type is fully replaced by the new implementation.
The class file of the redefined type is located by querying the redefined type's class loader by name. For specifying an alternative
ClassFileLocator
, useredefine(Class, ClassFileLocator)
.Note: When a user redefines a class with the purpose of reloading this class using a
ClassReloadingStrategy
, it is important that no fields or methods are added to the redefined class. Note that someImplementation
s implicitly add fields or methods. Finally, Byte Buddy might be forced to add a method if a redefined class already defines a class initializer. This can be disabled by settingwith(Implementation.Context.Factory)
to use aImplementation.Context.Disabled.Factory
where the class initializer is retained as is.- Type Parameters:
T
- The loaded type of the redefined type.- Parameters:
type
- The type that is being redefined.- Returns:
- A type builder for redefining the provided type.
-
redefine
Redefines the given type where any intercepted method that is declared by the redefined type is fully replaced by the new implementation.
Note: When a user redefines a class with the purpose of reloading this class using a
ClassReloadingStrategy
, it is important that no fields or methods are added to the redefined class. Note that someImplementation
s implicitly add fields or methods. Finally, Byte Buddy might be forced to add a method if a redefined class already defines a class initializer. This can be disabled by settingwith(Implementation.Context.Factory)
to use aImplementation.Context.Disabled.Factory
where the class initializer is retained as is.- Type Parameters:
T
- The loaded type of the redefined type.- Parameters:
type
- The type that is being redefined.classFileLocator
- The class file locator that is queried for the redefined type's class file.- Returns:
- A type builder for redefining the provided type.
-
redefine
Redefines the given type where any intercepted method that is declared by the redefined type is fully replaced by the new implementation.
Note: When a user redefines a class with the purpose of reloading this class using a
ClassReloadingStrategy
, it is important that no fields or methods are added to the redefined class. Note that someImplementation
s implicitly add fields or methods. Finally, Byte Buddy might be forced to add a method if a redefined class already defines a class initializer. This can be disabled by settingwith(Implementation.Context.Factory)
to use aImplementation.Context.Disabled.Factory
where the class initializer is retained as is.- Type Parameters:
T
- The loaded type of the redefined type.- Parameters:
type
- The type that is being redefined.classFileLocator
- The class file locator that is queried for the redefined type's class file.- Returns:
- A type builder for redefining the provided type.
-
rebase
Rebases the given type where any intercepted method that is declared by the redefined type is preserved within the rebased type's class such that the class's original can be invoked from the new method implementations. Rebasing a type can be seen similarly to creating a subclass where the subclass is later merged with the original class file.
The class file of the rebased type is located by querying the rebased type's class loader by name. For specifying an alternative
ClassFileLocator
, useredefine(Class, ClassFileLocator)
.- Type Parameters:
T
- The loaded type of the rebased type.- Parameters:
type
- The type that is being rebased.- Returns:
- A type builder for rebasing the provided type.
-
rebase
Rebases the given type where any intercepted method that is declared by the redefined type is preserved within the rebased type's class such that the class's original can be invoked from the new method implementations. Rebasing a type can be seen similarly to creating a subclass where the subclass is later merged with the original class file.
When a method is rebased, the original method is copied into a new method with a different name. These names are generated automatically by Byte Buddy unless a
MethodNameTransformer
is specified explicitly. Userebase(Class, ClassFileLocator, MethodNameTransformer)
for doing so.- Type Parameters:
T
- The loaded type of the rebased type.- Parameters:
type
- The type that is being rebased.classFileLocator
- The class file locator that is queried for the rebased type's class file.- Returns:
- A type builder for rebasing the provided type.
-
rebase
public <T> DynamicType.Builder<T> rebase(Class<T> type, ClassFileLocator classFileLocator, MethodNameTransformer methodNameTransformer) Rebases the given type where any intercepted method that is declared by the redefined type is preserved within the rebased type's class such that the class's original can be invoked from the new method implementations. Rebasing a type can be seen similarly to creating a subclass where the subclass is later merged with the original class file.- Type Parameters:
T
- The loaded type of the rebased type.- Parameters:
type
- The type that is being rebased.classFileLocator
- The class file locator that is queried for the rebased type's class file.methodNameTransformer
- The method name transformer for renaming a method that is rebased.- Returns:
- A type builder for rebasing the provided type.
-
rebase
Rebases the given type where any intercepted method that is declared by the redefined type is preserved within the rebased type's class such that the class's original can be invoked from the new method implementations. Rebasing a type can be seen similarly to creating a subclass where the subclass is later merged with the original class file.
When a method is rebased, the original method is copied into a new method with a different name. These names are generated automatically by Byte Buddy unless a
MethodNameTransformer
is specified explicitly. Userebase(TypeDescription, ClassFileLocator, MethodNameTransformer)
for doing so.- Type Parameters:
T
- The loaded type of the rebased type.- Parameters:
type
- The type that is being rebased.classFileLocator
- The class file locator that is queried for the rebased type's class file.- Returns:
- A type builder for rebasing the provided type.
-
rebase
public <T> DynamicType.Builder<T> rebase(TypeDescription type, ClassFileLocator classFileLocator, MethodNameTransformer methodNameTransformer) Rebases the given type where any intercepted method that is declared by the redefined type is preserved within the rebased type's class such that the class's original can be invoked from the new method implementations. Rebasing a type can be seen similarly to creating a subclass where the subclass is later merged with the original class file.- Type Parameters:
T
- The loaded type of the rebased type.- Parameters:
type
- The type that is being rebased.classFileLocator
- The class file locator that is queried for the rebased type's class file.methodNameTransformer
- The method name transformer for renaming a method that is rebased.- Returns:
- A type builder for rebasing the provided type.
-
rebase
Rebases a package. This offers an opportunity to add annotations to the package definition. Packages are defined by classes namedpackage-info
without any methods or fields but permit annotations. Any field or method definition will cause anIllegalStateException
to be thrown when the type is created.- Parameters:
aPackage
- The package that is being rebased.classFileLocator
- The class file locator to use for locating the package's class file.- Returns:
- A type builder for rebasing the given package.
-
rebase
public DynamicType.Builder<?> rebase(PackageDescription aPackage, ClassFileLocator classFileLocator) Rebases a package. This offers an opportunity to add annotations to the package definition. Packages are defined by classes namedpackage-info
without any methods or fields but permit annotations. Any field or method definition will cause anIllegalStateException
to be thrown when the type is created.- Parameters:
aPackage
- The package that is being rebased.classFileLocator
- The class file locator to use for locating the package's class file.- Returns:
- A type builder for rebasing the given package.
-
decorate
Decorates a type with
AsmVisitorWrapper
and allows adding attributes and annotations. A decoration does not allow for any standard transformations but can be used as a performance optimization compared to a redefinition, especially when implementing a Java agent that only applies ASM-based code changes.Important: Only use this mode to improve performance in a narrowly defined transformation. Using other features as those mentioned might result in an unexpected outcome of the transformation or error. Using decoration also requires the configuration of an
Implementation.Context.Factory
that does not attempt any type transformation.- Type Parameters:
T
- The loaded type of the decorated type.- Parameters:
type
- The type to decorate.- Returns:
- A type builder for decorating the provided type.
-
decorate
Decorates a type with
AsmVisitorWrapper
and allows adding attributes and annotations. A decoration does not allow for any standard transformations but can be used as a performance optimization compared to a redefinition, especially when implementing a Java agent that only applies ASM-based code changes.Important: Only use this mode to improve performance in a narrowly defined transformation. Using other features as those mentioned might result in an unexpected outcome of the transformation or error. Using decoration also requires the configuration of an
Implementation.Context.Factory
that does not attempt any type transformation.- Type Parameters:
T
- The loaded type of the decorated type.- Parameters:
type
- The type to decorate.classFileLocator
- The class file locator to use.- Returns:
- A type builder for decorating the provided type.
-
decorate
Decorates a type with
AsmVisitorWrapper
and allows adding attributes and annotations. A decoration does not allow for any standard transformations but can be used as a performance optimization compared to a redefinition, especially when implementing a Java agent that only applies ASM-based code changes.Important: Only use this mode to improve performance in a narrowly defined transformation. Using other features as those mentioned might result in an unexpected outcome of the transformation or error. Using decoration also requires the configuration of an
Implementation.Context.Factory
that does not attempt any type transformation.- Type Parameters:
T
- The loaded type of the decorated type.- Parameters:
type
- The type to decorate.classFileLocator
- The class file locator to use.- Returns:
- A type builder for decorating the provided type.
-
with
Creates a new configuration where all class files that are not based on an existing class file are created using the supplied class file version. When creating a Byte Buddy instance byByteBuddy()
, the class file version is detected automatically. If the class file version is known before creating a Byte Buddy instance, theByteBuddy(ClassFileVersion)
constructor should be used.- Parameters:
classFileVersion
- The class file version to use for types that are not based on an existing class file.- Returns:
- A new Byte Buddy instance that uses the supplied class file version.
-
with
Creates a new configuration where new types are named by applying the given naming strategy. By default, Byte Buddy simply retains the name of rebased and redefined types but adds a random suffix to the name of created subclasses or -interfaces. If a type is defined within thejava.*
namespace, Byte Buddy also adds a suffix to the generated class because this namespace is only available for the bootstrap class loader.- Parameters:
namingStrategy
- The naming strategy to apply when creating a new dynamic type.- Returns:
- A new Byte Buddy instance that uses the supplied naming strategy.
-
with
Creates a new configuration where auxiliary types are named by applying the given naming strategy. Auxiliary types are helper types that might be required for implementing certainImplementation
s. By default, Byte Buddy adds a random suffix to the instrumented type's name when naming its auxiliary types.- Parameters:
auxiliaryTypeNamingStrategy
- The naming strategy to apply when creating a new auxiliary type.- Returns:
- A new Byte Buddy instance that uses the supplied naming strategy for auxiliary types.
-
with
Creates a new configuration where annotation values are written according to the given filter factory. Using a filter factory, it is for example possible not to include certain values into a class file such that the runtime returns an annotation type's default value. By default, Byte Buddy includes all values into a class file, also such values for which a default value exists.- Parameters:
annotationValueFilterFactory
- The annotation value filter factory to use.- Returns:
- A new Byte Buddy instance that uses the supplied annotation value filter factory.
-
with
Creates a new configuration where annotations that are found in an existing class file are or are not preserved in the format they are discovered, i.e. rewritten in the format they were already present in the class file. By default, Byte Buddy retains annotations when a class is rebased or redefined.
Warning: Retaining annotations can cause problems when annotations of a field or method are added based on the annotations of a matched method. Doing so, Byte Buddy might write the annotations of the field or method explicitly to a class file while simultaneously retaining the existing annotation what results in duplicates. When matching fields or methods while adding annotations, disabling annotation retention might be required.
- Parameters:
annotationRetention
- The annotation retention strategy to use.- Returns:
- A new Byte Buddy instance that uses the supplied annotation retention strategy.
-
with
Creates a new configuration where theImplementation.Context
of any created type is a product of the given implementation context factory. An implementation context might imply unwanted side-effects, for example, the creation of an additional synthetic methods in order to support specific features for realizing anImplementation
. By default, Byte Buddy supplies a factory that enables all features. When redefining a loaded class, it is however required by the JVM that no additional members are added such that aImplementation.Context.Disabled
factory might be more appropriate.- Parameters:
implementationContextFactory
- The implementation context factory to use for defining an instrumented type.- Returns:
- A new Byte Buddy instance that uses the supplied implementation context factory.
-
with
Creates a new configuration where theMethodGraph.Compiler
is used for creating aMethodGraph
of the instrumented type. A method graph is a representation of a type's virtual methods, including all information on bridge methods that are inserted by the Java compiler. Creating a method graph is a rather expensive operation and more efficient strategies might exist for certain types or ava types that are created by alternative JVM languages. By default, a general purpose method graph compiler is used that uses the information that is exposed by the generic type information that is embedded in any class file.- Parameters:
methodGraphCompiler
- The method graph compiler to use for analyzing the instrumented type.- Returns:
- A new Byte Buddy instance that uses the supplied method graph compiler.
-
with
Configures Byte Buddy to use the specified factory for creatingInstrumentedType
s. Doing so, more efficient representations can be chosen when only certain operations are required. By default, all operations are supported.- Parameters:
instrumentedTypeFactory
- The factory to use when creating instrumented types.- Returns:
- A new Byte Buddy instance that uses the supplied factory for creating instrumented types.
-
with
Creates a new configuration that applies the supplied type validation. By default, explicitly type validation is applied by Byte Buddy but it might be disabled for performance reason or for voluntarily creating illegal types. The Java virtual machine applies its own type validation where someError
is thrown if a type is invalid, while Byte Buddy throws someRuntimeException
.- Parameters:
typeValidation
- The type validation to apply during type creation.- Returns:
- A new Byte Buddy instance that applies the supplied type validation.
-
with
Creates a new configuration that applies the supplied visibility bridge strategy. By default, visibility bridges are create for all methods for which a visibility bridge is normally necessary.- Parameters:
visibilityBridgeStrategy
- The visibility bridge strategy to apply.- Returns:
- A new Byte Buddy instance that applies the supplied visibility bridge strategy.
-
with
Creates a new configuration that applies the supplied class writer strategy. By default, the constant pool of redefined and retransformed classes is retained as most changes are additive and this retention improves performance.- Parameters:
classWriterStrategy
- The class writer strategy to apply during type creation.- Returns:
- A new Byte Buddy instance that applies the supplied class writer strategy.
-
ignore
Creates a new configuration where anyMethodDescription
that matches the provided method matcher is excluded from instrumentation. Any previous matcher for ignored methods is replaced. By default, Byte Buddy ignores any synthetic method (bridge methods are handled automatically) and theObject.finalize()
method.- Parameters:
ignoredMethods
- A matcher for identifying methods to be excluded from instrumentation.- Returns:
- A new Byte Buddy instance that excludes any method from instrumentation if it is matched by the supplied matcher.
-
ignore
Creates a new configuration where any
MethodDescription
that matches the provided method matcher is excluded from instrumentation. Any previous matcher for ignored methods is replaced. By default, Byte Buddy ignores any synthetic method (bridge methods are handled automatically) and theObject.finalize()
method. Using a latent matcher gives opportunity to resolve anElementMatcher
based on the instrumented type before applying the matcher.- Parameters:
ignoredMethods
- A matcher for identifying methods to be excluded from instrumentation.- Returns:
- A new Byte Buddy instance that excludes any method from instrumentation if it is matched by the supplied matcher.
-