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

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

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,
                            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

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.