JavaTM 2 Platform
Standard Ed. 5.0

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.

JavaTM 2 Platform
Standard Ed. 5.0

Submit a bug or feature
For further API reference and developer documentation, see Java 2 SDK SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Copyright 2004 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.