java.lang.instrument

Interface Instrumentation

public interface Instrumentation

This class provides services needed to instrument Java programming language code. Instrumentation is the addition of byte-codes to methods for the purpose of gathering data to be utilized by tools. Since the changes are purely additive, these tools do not modify application state or behavior. Examples of such benign tools include monitoring agents, profilers, coverage analyzers, and event loggers.

The only way to access an instance of the Instrumentation interface is for the JVM to be launched in a way that indicates the agent class - see the package specification. The Instrumentation instance is passed to the premain method of the agent class. Once an agent acquires the Instrumentation instance, the agent may call methods on the instance at any time.

Since:
JDK1.5

Method Summary

void
addTransformer(ClassFileTransformer transformer)
Registers the supplied transformer.
Class<T>[]
getAllLoadedClasses()
Returns an array of all classes currently loaded by the JVM.
Class<T>[]
getInitiatedClasses(ClassLoader loader)
Returns an array of all classes for which loader is an initiating loader.
long
getObjectSize(Object objectToSize)
Returns an implementation-specific approximation of the amount of storage consumed by the specified object.
boolean
isRedefineClassesSupported()
Returns whether or not the current JVM configuration supports redefinition of classes.
void
redefineClasses(ClassDefinition[] definitions)
Redefine the supplied set of classes using the supplied class files.
boolean
removeTransformer(ClassFileTransformer transformer)
Unregisters the supplied transformer.

Method Details

addTransformer

public void addTransformer(ClassFileTransformer transformer)
Registers the supplied transformer. All future class definitions will be seen by the transformer, except definitions of classes upon which any registered transformer is dependent. If multiple transformers are registered, they will be called in the order added. If a transformer throws during execution, the JVM will still call the other registered transformers in order. The same transformer may be added more than once. All transformers registered with addTransformer will always see the class files before any external JVMTI ClassFileLoadHook event listener does.

This method is intended for use in instrumentation, as described in the class specification.

Parameters:
transformer - the transformer to register
Throws:
NullPointerException - if passed a null transformer
Usages and Demos :

View More Examples of addTransformer(ClassFileTransformer transformer)
   1: 
   2: import java.lang.instrument.Instrumentation;
   3: import java.lang.instrument.ClassFileTransformer;
   4:         ...
   5: 
   6:     public static void premain(String args, Instrumentation inst) {
   7:         ...
   8:         inst.addTransformer(transformerCollection);
   9:     }
  10:         ...
  11:     public static void addTransformer(ClassFileTransformer classFileTransformer) {
  12:         transformerCollection.addTransformer(classFileTransformer);

View Full Code Here
   1: 
   2: import java.lang.instrument.Instrumentation;
   3: import java.lang.instrument.ClassFileTransformer;
   4:         ...
   5: 
   6:     private static Instrumentation s_instrumentation;
   7: 
   8:         ...
   9: 
  10:     public static void premain(String options, Instrumentation instrumentation) {
  11:         s_instrumentation = instrumentation;
  12:         ...
  13:         s_instrumentation.addTransformer(s_transformer);

View Full Code Here
   1: 
   2:   public static void premain (String agentArgs, Instrumentation inst)
   3:     throws IOException {
   4:         ...
   5:       System.out.format ("In dcomp premain, agentargs ='%s', " +
   6:                        "Instrumentation = '%s'\n", agentArgs, inst);
   7:       System.out.printf ("Options settings: %n%s%n", options.settings());
   8:         ...
   9:     Transform transformer = new Transform();
  10:     inst.addTransformer(transformer);

View Full Code Here
   1: 
   2:   public static void premain (String agentArgs, Instrumentation inst)
   3:     throws IOException {
   4:         ...
   5: 
   6:     inst.addTransformer((ClassFileTransformer) transformer);
   7:   }
   8: 
   9:   private static void readPurityFile(File purityFileName, File pathLoc)

View Full Code Here

getAllLoadedClasses

public Class<T>[] getAllLoadedClasses()
Returns an array of all classes currently loaded by the JVM.
Returns:
an array containing all the classes loaded by the JVM, zero-length if there are none

getInitiatedClasses

public Class<T>[] getInitiatedClasses(ClassLoader loader)
Returns an array of all classes for which loader is an initiating loader. If the supplied loader is null, classes initiated by the bootstrap class loader are returned.
Parameters:
loader - the loader whose initiated class list will be returned
Returns:
an array containing all the classes for which loader is an initiating loader, zero-length if there are none

getObjectSize

public long getObjectSize(Object objectToSize)
Returns an implementation-specific approximation of the amount of storage consumed by the specified object. The result may include some or all of the object's overhead, and thus is useful for comparison within an implementation but not between implementations. The estimate may change during a single invocation of the JVM.
Parameters:
objectToSize - the object to size
Returns:
an implementation-specific approximation of the amount of storage consumed by the specified object
Throws:
NullPointerException - if the supplied Object is null.
Usages and Demos :

View More Examples of getObjectSize(Object objectToSize)
   1: import java.lang.instrument.IllegalClassFormatException;
   2: import java.lang.instrument.Instrumentation;
   3: public class ExoInstrument {
   4:         ...
   5:   static private Instrumentation ins_ ;

View Full Code Here

isRedefineClassesSupported

public boolean isRedefineClassesSupported()
Returns whether or not the current JVM configuration supports redefinition of classes. The ability to redefine an already loaded class is an optional capability of a JVM. During a single instantiation of a single JVM, multiple calls to this method will always return the same answer.
Returns:
true if the current JVM configuration supports redefinition of classes, false if not.

redefineClasses

public void redefineClasses(ClassDefinition[] definitions)
            throws ClassNotFoundException,
                   UnmodifiableClassException
Redefine the supplied set of classes using the supplied class files. Operates on a set in order to allow interlocked changes to more than one class at the same time (a redefinition of class A can require a redefinition of class B).

If a redefined method has active stack frames, those active frames continue to run the bytecodes of the original method. The redefined method will be used on new invokes.

This method does not cause any initialization except that which would occur under the customary JVM semantics. In other words, redefining a class does not cause its initializers to be run. The values of static variables will remain as they were prior to the call.

Instances of the redefined class are not affected.

Registered transformers will be called before the redefine operation is applied.

The redefinition may change method bodies, the constant pool and attributes. The redefinition must not add, remove or rename fields or methods, change the signatures of methods, or change inheritance. These restrictions maybe be lifted in future versions.

A zero-length definitions array is allowed, in this case, this method does nothing.

If this method throws an exception, no classes have been redefined.

This method is intended for use in instrumentation, as described in the class specification.

Parameters:
definitions - array of classes to redefine with corresponding definitions
Throws:
ClassNotFoundException - if a specified class cannot be found
UnmodifiableClassException - if a specified class cannot be modified
UnsupportedOperationException - if the current configuration of the JVM does not allow redefinition (isRedefineClassesSupported() is false) or the redefinition made unsupported changes
NullPointerException - if the supplied definitions array or any of its components is null.

removeTransformer

public boolean removeTransformer(ClassFileTransformer transformer)
Unregisters the supplied transformer. Future class definitions will not be shown to the transformer. Removes the most-recently-added matching instance of the transformer. Due to the multi-threaded nature of class loading, it is possible for a transformer to receive calls after it has been removed. Transformers should be written defensively to expect this situation.
Parameters:
transformer - the transformer to unregister
Returns:
true if the transformer was found and removed, false if the transformer was not found
Throws:
NullPointerException - if passed a null transformer