net.bytebuddy

Class ByteBuddy

java.lang.Object

net.bytebuddy.ByteBuddy

@HashCodeAndEqualsPlugin.Enhance
public class ByteBuddy
extends Object

Instances of this class serve as a focus point for configuration of the library's behavior and as an entry point to any form of code generation using the library. For this purpose, Byte Buddy offers a fluent API which allows for the step-wise generation of a new Java type. A type is generated either by:

• 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.

Byte Buddy's API does not change when a type is rebased, redefined or subclassed. All types are created via the 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:

AgentBuilder

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	ByteBuddy.EnumerationImplementation An implementation fo the values method of an enumeration type.
protected static class	ByteBuddy.RecordConstructorStrategy A constructor strategy for implementing a Java record.
protected static class	ByteBuddy.RecordObjectMethod Implements the object methods of the Java record type.

Field Summary

Fields

Modifier and Type	Field and Description
protected AnnotationRetention	annotationRetention The annotation retention strategy to use.
protected AnnotationValueFilter.Factory	annotationValueFilterFactory The annotation value filter factory to use.
protected AuxiliaryType.NamingStrategy	auxiliaryTypeNamingStrategy The naming strategy to use for naming auxiliary types.
protected ClassFileVersion	classFileVersion The class file version to use for types that are not based on an existing class file.
protected ClassWriterStrategy	classWriterStrategy The class writer strategy to use.
static String	DEFAULT_NAMING_PROPERTY A property that controls the default naming strategy.
protected LatentMatcher<? super MethodDescription>	ignoredMethods A matcher for identifying methods that should be excluded from instrumentation.
protected Implementation.Context.Factory	implementationContextFactory The implementation context factory to use.
protected InstrumentedType.Factory	instrumentedTypeFactory The instrumented type factory to use.
protected MethodGraph.Compiler	methodGraphCompiler The method graph compiler to use.
protected NamingStrategy	namingStrategy The naming strategy to use.
protected TypeValidation	typeValidation Determines if a type should be explicitly validated.
protected VisibilityBridgeStrategy	visibilityBridgeStrategy The visibility bridge strategy to apply.

Constructor Summary

Constructors

Modifier	Constructor and Description
	ByteBuddy() Creates 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 Type	Method and Description
<T> DynamicType.Builder<T>	decorate(Class<T> type) Decorates a type with AsmVisitorWrapper and allows adding attributes and annotations.
<T> DynamicType.Builder<T>	decorate(Class<T> type, ClassFileLocator classFileLocator) Decorates a type with AsmVisitorWrapper and allows adding attributes and annotations.
<T> DynamicType.Builder<T>	decorate(TypeDescription type, ClassFileLocator classFileLocator) Decorates a type with AsmVisitorWrapper and allows adding attributes and annotations.
ByteBuddy	ignore(ElementMatcher<? super MethodDescription> ignoredMethods) Creates a new configuration where any MethodDescription that matches the provided method matcher is excluded from instrumentation.
ByteBuddy	ignore(LatentMatcher<? super MethodDescription> ignoredMethods) Creates a new configuration where any MethodDescription that matches the provided method matcher is excluded from instrumentation.
DynamicType.Builder<? extends Annotation>	makeAnnotation() Creates a new Annotation type.
DynamicType.Builder<? extends Enum<?>>	makeEnumeration(Collection<? extends String> values) Creates a new Enum type.
DynamicType.Builder<? extends Enum<?>>	makeEnumeration(String... value) Creates a new Enum type.
DynamicType.Builder<?>	makeInterface() Creates a new, plain interface type.
<T> DynamicType.Builder<T>	makeInterface(Class<T> interfaceType) Creates a new interface type that extends the provided interface.
DynamicType.Builder<?>	makeInterface(Collection<? extends TypeDefinition> interfaceTypes) Creates a new interface type that extends the provided interface.
DynamicType.Builder<?>	makeInterface(List<? extends Type> interfaceTypes) Creates a new interface type that extends the provided interface.
DynamicType.Builder<?>	makeInterface(Type... interfaceType) Creates a new interface type that extends the provided interface.
DynamicType.Builder<?>	makeInterface(TypeDefinition... interfaceType) Creates a new interface type that extends the provided interface.
DynamicType.Builder<?>	makePackage(String name) Creates a new package definition.
DynamicType.Builder<?>	makeRecord() Creates a new Java record.
<T> DynamicType.Builder<T>	rebase(Class<T> type) 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.
DynamicType.Builder<?>	rebase(Package aPackage, ClassFileLocator classFileLocator) Rebases a package.
DynamicType.Builder<?>	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>	redefine(Class<T> type) 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>	subclass(Class<T> superType) 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.
DynamicType.Builder<?>	subclass(Type superType) Creates a new builder for subclassing the provided type.
DynamicType.Builder<?>	subclass(Type superType, ConstructorStrategy constructorStrategy) Creates a new builder for subclassing the provided type.
DynamicType.Builder<?>	subclass(TypeDefinition superType) Creates a new builder for subclassing the provided type.
DynamicType.Builder<?>	subclass(TypeDefinition superType, ConstructorStrategy constructorStrategy) Creates a new builder for subclassing the provided type.
ByteBuddy	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.
ByteBuddy	with(AnnotationValueFilter.Factory annotationValueFilterFactory) Creates a new configuration where annotation values are written according to the given filter factory.
ByteBuddy	with(AuxiliaryType.NamingStrategy auxiliaryTypeNamingStrategy) Creates a new configuration where auxiliary types are named by applying the given naming strategy.
ByteBuddy	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.
ByteBuddy	with(ClassWriterStrategy classWriterStrategy) Creates a new configuration that applies the supplied class writer strategy.
ByteBuddy	with(Implementation.Context.Factory implementationContextFactory) Creates a new configuration where the Implementation.Context of any created type is a product of the given implementation context factory.
ByteBuddy	with(InstrumentedType.Factory instrumentedTypeFactory) Configures Byte Buddy to use the specified factory for creating InstrumentedTypes.
ByteBuddy	with(MethodGraph.Compiler methodGraphCompiler) Creates a new configuration where the MethodGraph.Compiler is used for creating a MethodGraph of the instrumented type.
ByteBuddy	with(NamingStrategy namingStrategy) Creates a new configuration where new types are named by applying the given naming strategy.
ByteBuddy	with(TypeValidation typeValidation) Creates a new configuration that applies the supplied type validation.
ByteBuddy	with(VisibilityBridgeStrategy visibilityBridgeStrategy) Creates a new configuration that applies the supplied visibility bridge strategy.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_NAMING_PROPERTY

public static final String 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 to fixed, Byte Buddy is setting names deterministically without any random element, or to caller, 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:

Constant Field Values

classFileVersion

protected final ClassFileVersion classFileVersion

The class file version to use for types that are not based on an existing class file.

namingStrategy

protected final NamingStrategy namingStrategy

The naming strategy to use.

auxiliaryTypeNamingStrategy

protected final AuxiliaryType.NamingStrategy auxiliaryTypeNamingStrategy

The naming strategy to use for naming auxiliary types.

annotationValueFilterFactory

protected final AnnotationValueFilter.Factory annotationValueFilterFactory

The annotation value filter factory to use.

annotationRetention

protected final AnnotationRetention annotationRetention

The annotation retention strategy to use.

implementationContextFactory

protected final Implementation.Context.Factory implementationContextFactory

The implementation context factory to use.

methodGraphCompiler

protected final MethodGraph.Compiler methodGraphCompiler

The method graph compiler to use.

instrumentedTypeFactory

protected final InstrumentedType.Factory instrumentedTypeFactory

The instrumented type factory to use.

ignoredMethods

protected final LatentMatcher<? super MethodDescription> ignoredMethods

A matcher for identifying methods that should be excluded from instrumentation.

typeValidation

protected final TypeValidation typeValidation

Determines if a type should be explicitly validated.

visibilityBridgeStrategy

protected final VisibilityBridgeStrategy visibilityBridgeStrategy

The visibility bridge strategy to apply.

classWriterStrategy

protected final ClassWriterStrategy classWriterStrategy

The class writer strategy to use.

Constructor Detail

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.

See Also:

ClassFileVersion.ofThisVm(ClassFileVersion)

ByteBuddy

public ByteBuddy(ClassFileVersion classFileVersion)

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 Detail

subclass

public <T> DynamicType.Builder<T> subclass(Class<T> superType)

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 by subclass(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

public DynamicType.Builder<?> subclass(Type superType)

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 by subclass(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

public DynamicType.Builder<?> subclass(Type 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 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

public DynamicType.Builder<?> subclass(TypeDefinition superType)

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 explicit ConstructorStrategy by subclass(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

public DynamicType.Builder<?> 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

public <T> DynamicType.Builder<T> makeInterface(Class<T> interfaceType)

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

public DynamicType.Builder<?> makeInterface(Type... interfaceType)

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

public DynamicType.Builder<?> makeInterface(List<? extends Type> interfaceTypes)

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

public DynamicType.Builder<?> makeInterface(TypeDefinition... interfaceType)

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

public DynamicType.Builder<?> makeInterface(Collection<? extends TypeDefinition> interfaceTypes)

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

public DynamicType.Builder<?> makePackage(String name)

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 an IllegalStateException 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

public DynamicType.Builder<?> 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

public DynamicType.Builder<? extends Annotation> 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

public DynamicType.Builder<? extends Enum<?>> makeEnumeration(String... value)

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

public DynamicType.Builder<? extends Enum<?>> makeEnumeration(Collection<? extends String> values)

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

public <T> DynamicType.Builder<T> redefine(Class<T> type)

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, use redefine(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 some Implementations 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 setting with(Implementation.Context.Factory) to use a Implementation.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

public <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.

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 some Implementations 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 setting with(Implementation.Context.Factory) to use a Implementation.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

public <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.

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 some Implementations 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 setting with(Implementation.Context.Factory) to use a Implementation.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

public <T> DynamicType.Builder<T> rebase(Class<T> type)

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, use redefine(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

public <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. 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. Use rebase(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

public <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. 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. Use rebase(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

public DynamicType.Builder<?> rebase(Package aPackage,
                                     ClassFileLocator classFileLocator)

Rebases a package. This offers an opportunity to add annotations to the package definition. Packages are defined by classes named package-info without any methods or fields but permit annotations. Any field or method definition will cause an IllegalStateException 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 named package-info without any methods or fields but permit annotations. Any field or method definition will cause an IllegalStateException 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

public <T> DynamicType.Builder<T> decorate(Class<T> type)

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

public <T> DynamicType.Builder<T> decorate(Class<T> type,
                                           ClassFileLocator classFileLocator)

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

public <T> DynamicType.Builder<T> decorate(TypeDescription type,
                                           ClassFileLocator classFileLocator)

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

public ByteBuddy 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. When creating a Byte Buddy instance by ByteBuddy(), the class file version is detected automatically. If the class file version is known before creating a Byte Buddy instance, the ByteBuddy(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

public ByteBuddy with(NamingStrategy namingStrategy)

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 the java.* 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

public ByteBuddy with(AuxiliaryType.NamingStrategy auxiliaryTypeNamingStrategy)

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 certain Implementations. 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

public ByteBuddy with(AnnotationValueFilter.Factory annotationValueFilterFactory)

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

public ByteBuddy 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. 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

public ByteBuddy with(Implementation.Context.Factory implementationContextFactory)

Creates a new configuration where the Implementation.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 an Implementation. 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 a Implementation.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

public ByteBuddy with(MethodGraph.Compiler methodGraphCompiler)

Creates a new configuration where the MethodGraph.Compiler is used for creating a MethodGraph 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

public ByteBuddy with(InstrumentedType.Factory instrumentedTypeFactory)

Configures Byte Buddy to use the specified factory for creating InstrumentedTypes. 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

public ByteBuddy with(TypeValidation typeValidation)

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 some Error is thrown if a type is invalid, while Byte Buddy throws some RuntimeException.

Parameters:

typeValidation - The type validation to apply during type creation.

Returns:

A new Byte Buddy instance that applies the supplied type validation.

with

public ByteBuddy with(VisibilityBridgeStrategy visibilityBridgeStrategy)

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

public ByteBuddy with(ClassWriterStrategy classWriterStrategy)

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

public ByteBuddy ignore(ElementMatcher<? super MethodDescription> ignoredMethods)

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 the Object.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

public ByteBuddy ignore(LatentMatcher<? super MethodDescription> ignoredMethods)

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 the Object.finalize() method. Using a latent matcher gives opportunity to resolve an ElementMatcher 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.