Instrumentation

java.lang.instrument
Interface Instrumentation

public interface Instrumentation

A set of services that allows an agent to interrogate and modify the JVM runtime environment.

The only way to access an instance of the Instrumentation interface is to use the -javaagent command line switch; this will cause an Instrumentation instance to be passed to the premain method. Once an agent acquires the Instrumentation instance, the agent may call methods on the instance at any time.

Since:: JDK1.5
See Also:: FIXME add xref to -javaagent docs

Method Summary

void addTransformer(ClassFileTransformer transformer)
          Registers the supplied transformer.

void appendToBootstrapClassLoaderSearch(String newSegment)
          After the bootstrap class loader unsuccessfully searches for a class, the specified platform-dependent search path segment (newSegment) will be searched as well.

void appendToClassPath(String newSegment)
          The specified platform-dependent search path segment (newSegment) will be appended to the Java class path - System.getProperty("java.class.path") - and that change will be applied to the system class loader.

Class[] getAllLoadedClasses()
          Returns an array of all classes currently loaded by the JVM.

Class[] 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 Summary
`void`	`addTransformer(ClassFileTransformer transformer)` Registers the supplied transformer.
`void`	`appendToBootstrapClassLoaderSearch(String newSegment)` After the bootstrap class loader unsuccessfully searches for a class, the specified platform-dependent search path segment (`newSegment`) will be searched as well.
`void`	`appendToClassPath(String newSegment)` The specified platform-dependent search path segment (`newSegment`) will be appended to the Java class path - `System.getProperty("java.class.path")` - and that change will be applied to the system class loader.
`Class[]`	`getAllLoadedClasses()` Returns an array of all classes currently loaded by the JVM.
`Class[]`	`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 Detail

addTransformer

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.

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

removeTransformer

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

isRedefineClassesSupported

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.
See Also:: redefineClasses(java.lang.instrument.ClassDefinition[])

redefineClasses

void redefineClasses(ClassDefinition[] definitions)
                     throws ClassNotFoundException

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 function 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, the method does nothing.

Parameters:: definitions - array of classes to redefine with corresponding definitions
Throws:: ClassNotFoundException - if a needed class cannot be found; UnsupportedOperationException - if the current configuration of the JVM does not allow redefinition (isRedefineClassesSupported() is false) or the redefinition made unsupported changes; ClassFormatError - if the data did not contain a valid class; NoClassDefFoundError - if the name in the class file is not equal to the name of the class; UnsupportedClassVersionError - if the class file version numbers are not supported; ClassCircularityError - if the new classes contain a circularity; LinkageError - if a linkage error occurs; NullPointerException - if the supplied definitions array or any of its components is null.
See Also:: isRedefineClassesSupported(), addTransformer(java.lang.instrument.ClassFileTransformer), ClassFileTransformer

getAllLoadedClasses

Class[] 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

Class[] 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

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.

appendToBootstrapClassLoaderSearch

void appendToBootstrapClassLoaderSearch(String newSegment)

After the bootstrap class loader unsuccessfully searches for a class, the specified platform-dependent search path segment (newSegment) will be searched as well. This method can be used to cause instrumentation classes to be defined by the bootstrap class loader. Only one segment (typically a directory or JAR file) may be specified in newSegment. This method may be called multiple times to add multiple segments, the segments will be searched in the order that this method was called. The definition of a well-formed segment is platform dependent, but a well-formed segment must not include the platform specific segment separator (unless it is escaped).

Parameters:: newSegment - the new segment to be searched by the bootstrap class loader
Throws:: NullPointerException - if the supplied newSegment is null.; IllegalArgumentException - if the supplied newSegment is malformed.

appendToClassPath

void appendToClassPath(String newSegment)

The specified platform-dependent search path segment (newSegment) will be appended to the Java class path - System.getProperty("java.class.path") - and that change will be applied to the system class loader. This method can be used to cause instrumentation classes to be defined by the system class loader. Only one segment (typically a directory or JAR file) may be specified in newSegment. This method may be called multiple times to append multiple segments. The definition of a well-formed segment is platform dependent, but a well-formed segment must not include the platform specific segment separator (unless it is escaped).

Parameters:: newSegment - the new segment to append to the system loader class path
Throws:: NullPointerException - if the supplied newSegment is null.; IllegalArgumentException - if the supplied newSegment is malformed.

java.lang.instrument Interface Instrumentation