net.lenni0451.classtransform

Class TransformerManager

java.lang.Object

net.lenni0451.classtransform.TransformerManager

All Implemented Interfaces:

java.lang.instrument.ClassFileTransformer

@ParametersAreNonnullByDefault
public class TransformerManager
extends java.lang.Object
implements java.lang.instrument.ClassFileTransformer

The TransformerManager handles all things needed for class transformation.
This class implements ClassFileTransformer so it can be used with an Instrumentation agent.

See Also:

GitHub Wiki

Constructor Summary

Constructors

Constructor and Description
TransformerManager(IClassProvider classProvider)
TransformerManager(IClassProvider classProvider, AMapper mapper)

Method Summary

Modifier and Type	Method and Description
void	addBytecodeTransformer(IBytecodeTransformer bytecodeTransformer) Add a bytecode transformer to the transformer list. Bytecode transformer are the ClassTransform implementation of ClassFileTransformer .
void	addClassFileTransformer(java.lang.ClassLoader classLoader, java.lang.instrument.ClassFileTransformer classFileTransformer) Add a ClassFileTransformer to the transformer list. The classLoader is directly passed to the transformer.
void	addCoprocessor(java.util.function.Supplier<? extends IAnnotationCoprocessor> coprocessorSupplier) Add a new annotation handler coprocessor. A new coprocessor instance will be created for each annotation handler.
void	addCustomAnnotationHandler(AnnotationHandler transformer, HandlerPosition handlerPosition) Add a custom annotation handler into the handler chain.
void	addInjectionTarget(java.lang.String name, IInjectionTarget target) Add a new injection target for use with the CTarget annotation.
void	addPostTransformConsumer(IPostTransformer postTransformer) Add a post transformer to handle the raw bytecode after all transformer have been applied. Useful for dumping transformed classes to disk.
void	addRawTransformer(java.lang.String className, IRawTransformer rawTransformer) Add a raw class transformer to the transformer list. Raw class transformer are similar to bytecode transformer but only for the specified class. A ClassNode is passed to the transformer instead of the bytecode array.
java.util.Set<java.lang.String>	addTransformer(org.objectweb.asm.tree.ClassNode classNode) Add a ClassNode directly to the transformer list. The class must still be annotated with CTransformer.
java.util.Set<java.lang.String>	addTransformer(org.objectweb.asm.tree.ClassNode classNode, boolean requireAnnotation) Add a ClassNode directly to the transformer list. The class must still be annotated with CTransformer.
java.util.Set<java.lang.String>	addTransformer(org.objectweb.asm.tree.ClassNode classNode, boolean requireAnnotation, boolean retransformClasses) Add a ClassNode directly to the transformer list. The class must still be annotated with CTransformer.
void	addTransformer(java.lang.String transformer) Add a transformer class to the transformer list. Use the direct class name for a single transformer (e.g.
void	addTransformerPreprocessor(IAnnotationHandlerPreprocessor annotationHandlerPreprocessor) Add an annotation handler preprocessor to the preprocessor list. You can modify class transform annotations before they get parsed.
IClassProvider	getClassProvider()
ClassTree	getClassTree()
AnnotationCoprocessorList	getCoprocessors() Create and get a new array of all coprocessors.
TransformerDebugger	getDebugger()
FailStrategy	getFailStrategy()
java.util.Optional<IInjectionTarget>	getInjectionTarget(java.lang.String name) Get an injection target by its name. The name is case-insensitive.
java.util.Map<java.lang.String,IInjectionTarget>	getInjectionTargets()
java.lang.instrument.Instrumentation	getInstrumentation()
AMapper	getMapper()
java.util.Set<java.lang.String>	getRegisteredTransformer()
java.util.Set<java.lang.String>	getTransformedClasses()
void	hookInstrumentation(java.lang.instrument.Instrumentation instrumentation) Hook an Instrumentation instance to allow for transformation using it. This allows to transform classes already loaded by the JVM. You have to be careful with re-transforming classes since you can't modify the class structure (e.g.
void	hookInstrumentation(java.lang.instrument.Instrumentation instrumentation, boolean hotswappable) Hook an Instrumentation instance to allow for transformation using it. This allows to transform classes already loaded by the JVM. You have to be careful with re-transforming classes since you can't modify the class structure (e.g.
void	setFailStrategy(FailStrategy failStrategy) Set the fail strategy used when a transformer fails.
byte[]	transform(java.lang.ClassLoader loader, java.lang.String className, java.lang.Class<?> classBeingRedefined, java.security.ProtectionDomain protectionDomain, byte[] classfileBuffer) Support method for hooking an instrumentation instance. You can simply add the TransformerManager as a transformer using Instrumentation.addTransformer(ClassFileTransformer) or call hookInstrumentation(Instrumentation).
byte[]	transform(java.lang.String name, byte[] bytecode) Transform the bytecode of the given class. The name must be in the class format (e.g.
byte[]	transform(java.lang.String name, byte[] bytecode, boolean calculateStackMapFrames) Transform the bytecode of the given class. The name must be in the class format (e.g.

Methods inherited from class java.lang.Object

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

Constructor Detail

TransformerManager

public TransformerManager(IClassProvider classProvider)

Parameters:

classProvider - The class provider used to get the class bytecode

TransformerManager

public TransformerManager(IClassProvider classProvider,
                          AMapper mapper)

Parameters:

classProvider - The class provider used to get the class bytecode

mapper - The mapper used to remap ClassTransform annotation targets and transformers if enabled

Method Detail

getClassTree

public ClassTree getClassTree()

Returns:

The class tree

getClassProvider

public IClassProvider getClassProvider()

Returns:

The class provider

getMapper

public AMapper getMapper()

Returns:

The mapper

getRegisteredTransformer

public java.util.Set<java.lang.String> getRegisteredTransformer()

Returns:

The names of all registered transformers

getTransformedClasses

public java.util.Set<java.lang.String> getTransformedClasses()

Returns:

The names of all transformed classes

addCoprocessor

public void addCoprocessor(java.util.function.Supplier<? extends IAnnotationCoprocessor> coprocessorSupplier)

Add a new annotation handler coprocessor.
A new coprocessor instance will be created for each annotation handler.

Parameters:

coprocessorSupplier - The coprocessor supplier

getCoprocessors

public AnnotationCoprocessorList getCoprocessors()

Create and get a new array of all coprocessors.

Returns:

The coprocessors

getInjectionTargets

public java.util.Map<java.lang.String,IInjectionTarget> getInjectionTargets()

Returns:

The injection targets

getInjectionTarget

public java.util.Optional<IInjectionTarget> getInjectionTarget(java.lang.String name)

Get an injection target by its name.
The name is case-insensitive.

Parameters:

name - The name of the injection target

Returns:

The injection target

getDebugger

public TransformerDebugger getDebugger()

Returns:

The debugger instance

setFailStrategy

public void setFailStrategy(FailStrategy failStrategy)

Set the fail strategy used when a transformer fails.

Parameters:

failStrategy - The fail strategy to use

getFailStrategy

public FailStrategy getFailStrategy()

Returns:

The current fail strategy

getInstrumentation

@Nullable
public java.lang.instrument.Instrumentation getInstrumentation()

Returns:

The instrumentation instance if hooked

addTransformerPreprocessor

public void addTransformerPreprocessor(IAnnotationHandlerPreprocessor annotationHandlerPreprocessor)

Add an annotation handler preprocessor to the preprocessor list.
You can modify class transform annotations before they get parsed.

Parameters:

annotationHandlerPreprocessor - The annotation handler preprocessor to add

addBytecodeTransformer

public void addBytecodeTransformer(IBytecodeTransformer bytecodeTransformer)

Add a bytecode transformer to the transformer list.
Bytecode transformer are the ClassTransform implementation of ClassFileTransformer .

Parameters:

bytecodeTransformer - The bytecode transformer to add

addClassFileTransformer

public void addClassFileTransformer(java.lang.ClassLoader classLoader,
                                    java.lang.instrument.ClassFileTransformer classFileTransformer)

Add a ClassFileTransformer to the transformer list.
The classLoader is directly passed to the transformer.

Parameters:

classLoader - The class loader of the class

classFileTransformer - The class file transformer to add

addRawTransformer

public void addRawTransformer(java.lang.String className,
                              IRawTransformer rawTransformer)

Add a raw class transformer to the transformer list.
Raw class transformer are similar to bytecode transformer but only for the specified class.
A ClassNode is passed to the transformer instead of the bytecode array.

Parameters:

className - The name of the class to transform

rawTransformer - The raw transformer to add

addTransformer

public void addTransformer(java.lang.String transformer)

Add a transformer class to the transformer list.
Use the direct class name for a single transformer (e.g. package.Transformer)
Use the package ending with '*' for all transformer in the packet (not sub packages) (e.g. package.*)
Use the package ending with '**' for all transformer in the package and sub packages (e.g. package.**)
If the class is specified directly an exception will be thrown if the class is missing the CTransformer annotation.

Parameters:

transformer - The name of transformer class to add

Throws:

java.lang.IllegalStateException - If the class is specified directly and is missing the CTransformer annotation

TransformerLoadException - If the transformer could not be loaded

java.lang.RuntimeException - If the class bytecode could not be parsed using ASM

addTransformer

public java.util.Set<java.lang.String> addTransformer(org.objectweb.asm.tree.ClassNode classNode)

Add a ClassNode directly to the transformer list.
The class must still be annotated with CTransformer.

Parameters:

classNode - The class node to add

Returns:

A set of all transformed classes

Throws:

java.lang.IllegalStateException - If the class is missing the CTransformer annotation

addTransformer

public java.util.Set<java.lang.String> addTransformer(org.objectweb.asm.tree.ClassNode classNode,
                                                      boolean requireAnnotation)

Add a ClassNode directly to the transformer list.
The class must still be annotated with CTransformer.

Parameters:

classNode - The class node to add

requireAnnotation - If an exception should be thrown if the class is missing the CTransformer annotation

Returns:

A set of all transformed classes

Throws:

java.lang.IllegalStateException - If the class is missing the CTransformer annotation and requireAnnotation is true

addTransformer

public java.util.Set<java.lang.String> addTransformer(org.objectweb.asm.tree.ClassNode classNode,
                                                      boolean requireAnnotation,
                                                      boolean retransformClasses)

Add a ClassNode directly to the transformer list.
The class must still be annotated with CTransformer.

Parameters:

classNode - The class node to add

requireAnnotation - If an exception should be thrown if the class is missing the CTransformer annotation

retransformClasses - Whether to retransform classes after adding the transformer (if instrumentation is hooked)

Returns:

A set of all transformed classes

Throws:

java.lang.IllegalStateException - If the class is missing the CTransformer annotation and requireAnnotation is true

addPostTransformConsumer

public void addPostTransformConsumer(IPostTransformer postTransformer)

Add a post transformer to handle the raw bytecode after all transformer have been applied.
Useful for dumping transformed classes to disk.

Parameters:

postTransformer - The BiConsumer instance

addCustomAnnotationHandler

public void addCustomAnnotationHandler(AnnotationHandler transformer,
                                       HandlerPosition handlerPosition)

Add a custom annotation handler into the handler chain.

Parameters:

transformer - The annotation handler to add

handlerPosition - The position where to add the handler

addInjectionTarget

public void addInjectionTarget(java.lang.String name,
                               IInjectionTarget target)

Add a new injection target for use with the CTarget annotation.

Parameters:

name - The name of the injection target

target - The injection target

transform

@Nullable
public byte[] transform(java.lang.String name,
                                  byte[] bytecode)

Transform the bytecode of the given class.
The name must be in the class format (e.g. java.lang.String).

Parameters:

name - The name of the class

bytecode - The bytecode of the class

Returns:

The modified bytecode of the class or null if not changed

transform

@Nullable
public byte[] transform(java.lang.String name,
                                  byte[] bytecode,
                                  boolean calculateStackMapFrames)

Transform the bytecode of the given class.
The name must be in the class format (e.g. java.lang.String).

Parameters:

name - The name of the class

bytecode - The bytecode of the class

calculateStackMapFrames - If the stack map frames should be calculated

Returns:

The modified bytecode of the class or null if not changed

hookInstrumentation

public void hookInstrumentation(java.lang.instrument.Instrumentation instrumentation)

Hook an Instrumentation instance to allow for transformation using it.
This allows to transform classes already loaded by the JVM.
You have to be careful with re-transforming classes since you can't modify the class structure (e.g. adding a new method or modifying the signature of an existing one). You can use the CInline annotation to prevent adding methods to a loaded class.
When using this method all loaded classes will be re-transformed if there is a transformer for them.
Hotswapping transformer is disabled by default as it causes a bit more overhead and memory usage.

Parameters:

instrumentation - The instrumentation instance to hook

hookInstrumentation

public void hookInstrumentation(java.lang.instrument.Instrumentation instrumentation,
                                boolean hotswappable)

Hook an Instrumentation instance to allow for transformation using it.
This allows to transform classes already loaded by the JVM.
You have to be careful with re-transforming classes since you can't modify the class structure (e.g. adding a new method or modifying the signature of an existing one). You can use the CInline annotation to prevent adding methods to a loaded class.
When using this method all loaded classes will be re-transformed if there is a transformer for them.

Parameters:

instrumentation - The instrumentation instance to hook

hotswappable - Whether to enable transformer hotswapping

transform

@Nullable
public byte[] transform(@Nullable
                                  java.lang.ClassLoader loader,
                                  @Nullable
                                  java.lang.String className,
                                  @Nullable
                                  java.lang.Class<?> classBeingRedefined,
                                  @Nullable
                                  java.security.ProtectionDomain protectionDomain,
                                  byte[] classfileBuffer)

Support method for hooking an instrumentation instance.
You can simply add the TransformerManager as a transformer using Instrumentation.addTransformer(ClassFileTransformer) or call hookInstrumentation(Instrumentation).

Specified by:

transform in interface java.lang.instrument.ClassFileTransformer