java.lang.instrument
public interface
public interface
java.lang.instrument.Instrumentation
| java.lang.instrument.Instrumentation |
Instances of this interface may be used by Java instrumentation agent code for support in carrying out the runtime instrumentation of classes. Using such an approach, classes may be enhanced with services such as profiling, logging or tracing which were not included in the source of the original class.
A concrete instance of this interface is made available as an input argument
to all Java instrumentation agents'
premain(String agentArgs, Instrumentation inst) method.
Summary
Public Methods
| void | addTransformer(ClassFileTransformer transformer) | ||||
Registers the supplied transformer argument with the VM. |
|||||
| Class[] | getAllLoadedClasses() | ||||
| Returns an array of all of the classes that have been loaded into the VM. | |||||
| Class[] | getInitiatedClasses(ClassLoader loader) | ||||
Returns an array of all of the classes for which loader is
the initiating class loader. |
|||||
| long | getObjectSize(Object objectToSize) | ||||
Returns the number of bytes in memory required by this VM for the
supplied object objectToSize. |
|||||
| boolean | isRedefineClassesSupported() | ||||
| Returns a boolean indication of whether or not this VM supports the on-the-fly redefining of classes that have been already loaded. | |||||
| void | redefineClasses(ClassDefinition[] definitions) | ||||
| Receives an array of ClassDefinition instances and attempts to carry out on-the-fly redefining on each of the associated classes. | |||||
| boolean | removeTransformer(ClassFileTransformer transformer) | ||||
Removes the most recently added instance of the
ClassFileTransformer object from the VM's list of
registered transformers. |
|||||
Details
Public Methods
public void addTransformer(ClassFileTransformer transformer)
Registers the supplied
transformer argument with the VM.
Any classes that are to be defined or re-defined (if supported) in the VM
will then be offered to the transformer for it to carry out any byte code
modifications. The exception to this scheme is if the class to be defined /
re-defined is a dependency of the transformer.
This operation can be carried out multiple times on a concrete
Instrumentation. The order of registration is important
as it defines the order in which the transformers' transformation
operation gets called.
It is possible for any given instance of
ClassFileTransformer to be registered more than once with
this operation.
Parameters
| transformer | a class file transformer |
|---|
Throws
| NullPointerException | if transformer is null.
|
|---|
public Class[] getAllLoadedClasses()
Returns an array of all of the classes that have been loaded into the VM.
Returns
- an array of
Classobjects with each element identifying a class that has been loaded into the VM.
public Class[] getInitiatedClasses(ClassLoader loader)
Returns an array of all of the classes for which
loader is
the initiating class loader.
Parameters
| loader | a class loader. In order to obtain the array of classes
initiated by the bootstrap class loader this argument should
be null. |
|---|
Returns
- an array of
Classobjects with each element identifying a class that has been initiated by the specified class loader.
public long getObjectSize(Object objectToSize)
Returns the number of bytes in memory required by this VM for the
supplied object
objectToSize. The returned value should
be taken as an estimation only which is susceptible to change between
separate launches of the VM.
Parameters
| objectToSize | any object |
|---|
Returns
- an approximation of the number of bytes in memory taken up by
objectToSize.
Throws
| NullPointerException | if the given object is null. |
|---|
public boolean isRedefineClassesSupported()
Returns a boolean indication of whether or not this VM supports the
on-the-fly redefining of classes that have been already loaded.
Returns
trueif class redefining is supported, otherwisefalse.
public void redefineClasses(ClassDefinition[] definitions)
Receives an array of ClassDefinition instances and attempts to
carry out on-the-fly redefining on each of the associated classes.
Redefining in this manner may be used to update the following parts of an
already loaded class:
Redefining a class may not be used to make changes to any other aspects of a previously loaded class such as its inheritance hierarchy, the names or signatures of any of its methods, the names of any fields, the values of any static variables etc.
- attributes
- constant pool
- method implementations
Redefining a class may not be used to make changes to any other aspects of a previously loaded class such as its inheritance hierarchy, the names or signatures of any of its methods, the names of any fields, the values of any static variables etc.
If a class associated with a ClassDefinition is
successfully redefined then there will be no resulting re-run of any of
its initialization code. Similarly, any instances of the class that were
created before the redefining will not be changed in any way. That is,
they will remain in the VM as instances of the previous version of the
class.
Note that before the requested redefinitions are attempted, each ClassFileTransformer registered with the VM will be given the opportunity to carry out their own custom transformations of the new version of the class.
Parameters
| definitions | an array of ClassDefinition objects wrapping
the details of the classes to be redefined. A zero-length
array value will not cause an error but, instead, will
silently do nothing. |
|---|
Throws
| ClassNotFoundException | if any of the classes specified in the contents of
definitions cannot be located. |
|---|---|
| UnmodifiableClassException | if any of the classes specified in the contents of
definitions cannot be modified. |
| UnsupportedOperationException | if this method is not supported in by the VM. May be checked in advance by calling isRedefineClassesSupported(). |
| ClassFormatError | if any of the definitions elements has been
created with a byte array containing a badly
formed class file. |
| NoClassDefFoundError | if there is disagreement between the name of a class to be redefined and the name of the class from the corresponding class file format byte array. |
| UnsupportedClassVersionError | if the version of any of the classes to be redefined is not supported by the VM. |
| ClassCircularityError | if a circular dependency is detected among the classes to be redefined. |
| LinkageError | if a linkage error situation is detected such that there is an incompatability between dependent classes. |
| NullPointerException | if definitions or any of its elements are
found to be null. |
See Also
public boolean removeTransformer(ClassFileTransformer transformer)
Removes the most recently added instance of the
ClassFileTransformer object from the VM's list of
registered transformers. After this call completes, the specified
ClassFileTransformer object will no longer have its
transform() method automatically invoked when class definitions or
redefinitions are attempted.
Parameters
transformer
a previously registered ClassFileTransformer.
Returns
true if transformer was located in
the list of registered transformers and successfully removed.
Otherwise, false.
Throws
NullPointerException
if transformer is null.