java.lang.instrument
Interface ClassFileTransformer


public interface ClassFileTransformer

An agent provides an implementation of this interface in order to transform class files. The transformation occurs before the class is defined by the JVM.

Note the term class file is used as defined in the chapter The class File Format of The Java Virtual Machine Specification, to mean a sequence of bytes in class file format, whether or not they reside in a file.

Since:
JDK1.5
See Also:
Instrumentation sample code for java.lang.instrument.Instrumentation definition code for java.lang.instrument.Instrumentation , Instrumentation.addTransformer(java.lang.instrument.ClassFileTransformer) sample code for java.lang.instrument.Instrumentation.addTransformer(java.lang.instrument.ClassFileTransformer) definition code for java.lang.instrument.Instrumentation.addTransformer(java.lang.instrument.ClassFileTransformer) , Instrumentation.removeTransformer(java.lang.instrument.ClassFileTransformer) sample code for java.lang.instrument.Instrumentation.removeTransformer(java.lang.instrument.ClassFileTransformer) definition code for java.lang.instrument.Instrumentation.removeTransformer(java.lang.instrument.ClassFileTransformer)

Method Summary
 byte[] transform sample code for java.lang.instrument.ClassFileTransformer.transform(java.lang.ClassLoader, java.lang.String, java.lang.Class, java.security.ProtectionDomain, byte[]) definition code for java.lang.instrument.ClassFileTransformer.transform(java.lang.ClassLoader, java.lang.String, java.lang.Class, java.security.ProtectionDomain, byte[]) (ClassLoader sample code for java.lang.ClassLoader definition code for java.lang.ClassLoader  loader, String sample code for java.lang.String definition code for java.lang.String  className, Class sample code for java.lang.Class definition code for java.lang.Class <?> classBeingRedefined, ProtectionDomain sample code for java.security.ProtectionDomain definition code for java.security.ProtectionDomain  protectionDomain, byte[] classfileBuffer)
          The implementation of this method may transform the supplied class file and return a new replacement class file.
 

Method Detail

transform sample code for java.lang.instrument.ClassFileTransformer.transform(java.lang.ClassLoader, java.lang.String, java.lang.Class<?>, java.security.ProtectionDomain, byte[]) definition code for java.lang.instrument.ClassFileTransformer.transform(java.lang.ClassLoader, java.lang.String, java.lang.Class<?>, java.security.ProtectionDomain, byte[])

byte[] transform(ClassLoader sample code for java.lang.ClassLoader definition code for java.lang.ClassLoader  loader,
                 String sample code for java.lang.String definition code for java.lang.String  className,
                 Class sample code for java.lang.Class definition code for java.lang.Class <?> classBeingRedefined,
                 ProtectionDomain sample code for java.security.ProtectionDomain definition code for java.security.ProtectionDomain  protectionDomain,
                 byte[] classfileBuffer)
                 throws IllegalClassFormatException sample code for java.lang.instrument.IllegalClassFormatException definition code for java.lang.instrument.IllegalClassFormatException 
The implementation of this method may transform the supplied class file and return a new replacement class file.

Once a transformer has been registered with Instrumentation.addTransformer sample code for java.lang.instrument.Instrumentation.addTransformer(java.lang.instrument.ClassFileTransformer) definition code for java.lang.instrument.Instrumentation.addTransformer(java.lang.instrument.ClassFileTransformer) , the transformer will be called for every new class definition and every class redefinition. The request for a new class definition is made with ClassLoader.defineClass sample code for java.lang.ClassLoader.defineClass(byte[], int, int) definition code for java.lang.ClassLoader.defineClass(byte[], int, int) . The request for a class redefinition is made with Instrumentation.redefineClasses sample code for java.lang.instrument.Instrumentation.redefineClasses(java.lang.instrument.ClassDefinition[]) definition code for java.lang.instrument.Instrumentation.redefineClasses(java.lang.instrument.ClassDefinition[]) or its native equivalents. The transformer is called during the processing of the request, before the class file bytes have been verified or applied.

If the implementing method determines that no transformations are needed, it should return null. Otherwise, it should create a new byte[] array, copy the input classfileBuffer into it, along with all desired transformations, and return the new array. The input classfileBuffer must not be modified.

In the redefine case, the transformer must support the redefinition semantics. If a class that the transformer changed during initial definition is later redefined, the transformer must insure that the second class output class file is a legal redefinition of the first output class file.

If the transformer believes the classFileBuffer does not represent a validly formatted class file, it should throw an IllegalClassFormatException. Subsequent transformers will still be called and the load or redefine will still be attempted. Throwing an IllegalClassFormatException thus has the same effect as returning null but facilitates the logging or debugging of format corruptions.

Parameters:
loader - the defining loader of the class to be transformed, may be null if the bootstrap loader
className - the name of the class in the internal form of fully qualified class and interface names as defined in The Java Virtual Machine Specification. For example, "java/util/List".
classBeingRedefined - if this is a redefine, the class being redefined, otherwise null
protectionDomain - the protection domain of the class being defined or redefined
classfileBuffer - the input byte buffer in class file format - must not be modified
Returns:
a well-formed class file buffer (the result of the transform), or null if no transform is performed.
Throws:
IllegalClassFormatException sample code for java.lang.instrument.IllegalClassFormatException definition code for java.lang.instrument.IllegalClassFormatException - if the input does not represent a well-formed class file
See Also:
Instrumentation.redefineClasses(java.lang.instrument.ClassDefinition[]) sample code for java.lang.instrument.Instrumentation.redefineClasses(java.lang.instrument.ClassDefinition[]) definition code for java.lang.instrument.Instrumentation.redefineClasses(java.lang.instrument.ClassDefinition[])