Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| JavaTM 2 Platform Standard Ed. 5.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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`.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| JavaTM 2 Platform Standard Ed. 5.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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.