ClassDefinition

This class is a simple wrapper around a Class object and an array of bytes that represents a class file for that class. An array of ClassDefinition objects is passed to the redefineClasses( ) method of the Instrumentation class. Class redefinitions are allowed to change method implementations , but not the members or inheritance of a class or the signature of the methods .

public final class

ClassDefinition

{

// Public Constructors

public

ClassDefinition

(Class<?>

theClass

, byte[ ]

theClassFile

);

// Public Instance Methods

public Class<?>

getDefinitionClass

( );  
     public byte[ ]

getDefinitionClassFile

( );  
}

Passed To

Instrumentation.redefineClasses( )

A ClassFileTransformer registered through an Instrumentation object is offered a chance to transform every class that is subsequently loaded or redefined. The final argument to transform( ) is a byte array that contains the raw bytes of the class file (or bytes returned by a previously invoked ClassFileTransformer ). If the TRansform( ) method wishes to transform the class, it should return the transformed bytes in a newly allocated array. The array passed to transform( ) should not be modified. If the transform( ) method does not wish to transform a given class, it should return null .

public interface

ClassFileTransformer

{

// Public Instance Methods

byte[ ]

transform

(ClassLoader

loader

, String

className

, Class<?>

classBeingRedefined

, 
java.security.ProtectionDomain

protectionDomain

, byte[ ]

classfileBuffer

) 
throws IllegalClassFormatException;  
}

Passed To

Instrumentation.{addTransformer( ) , removeTransformer( )}

A ClassFileTransformer should throw an exception of this type from its transform( ) method if it believes that the class file bytes it has been passed are malformed (this could happen, for example, if a defective ClassFileTransformer had previously transformed a valid class file).

Figure 10-83. java.lang.instrument.IllegalClassFormatException

public class

IllegalClassFormatException

extends Exception {

// Public Constructors

public

IllegalClassFormatException

( );  
     public

IllegalClassFormatException

(String

s

);  
}

Thrown By

ClassFileTransformer.transform( )

This interface is the main entry point to the java.lang.instrument API. A Java instrumentation agent specified on the Java interpreter command line with the -javaagent argument must be a class that defines the following method:

public static void premain(String args, Instrumentation instr)

The Java interpreter invokes the premain( ) method during startup before calling the main( ) method of the program. Any arguments specified with the -javaagent command line are passed in the first premain( ) argument, and an Instrumentation object is passed as the second argument.

The most powerful feature of the Instrumentation object is the ability to register ClassFileTransformer objects to augment or rewrite the byte code of Java class files as they are loaded into the interpreter. If isRedefineClassesSupported( ) returns true , you can also redefine already-loaded classes on the fly with redefineClasses( ) .

getAllLoadedClasses( ) returns an array of all classes loaded into the VM, and getInitiatedClasses( ) returns an array of classes loaded by a specified ClassLoader . getObjectSize( ) returns an implementation-specific approximation of the amount of memory required by a specified object.

public interface

Instrumentation

{

// Public Instance Methods

void

addTransformer

(ClassFileTransformer

transformer

);  
     Class[ ]

getAllLoadedClasses

( );  
     Class[ ]

getInitiatedClasses

(ClassLoader

loader

);  
     long

getObjectSize

(Object

objectToSize

);  
     boolean

isRedefineClassesSupported

( );  
     void

redefineClasses

(ClassDefinition[ ]

definitions

) throws ClassNotFoundException, 
     UnmodifiableClassException;  
     boolean

removeTransformer

(ClassFileTransformer

transformer

);  
}