|
| |
|
| java.lang.instrument.Instrumentation
| Instrumentation | | public interface Instrumentation (Code) | | 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.
|
| Method Summary | |
| 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. | | public Class[] | getAllLoadedClasses()
Returns an array of all of the classes that have 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. | | public long | getObjectSize(Object objectToSize)
Returns the number of bytes in memory required by this VM for the
supplied object objectToSize. | | 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. | | 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:
- attributes
- constant pool
- method implementations
If any invocations of a redefined method are already active in the VM
when this call is made then they will run to completion and be unaffected
by the outcome of this method. | | public boolean | removeTransformer(ClassFileTransformer transformer)
Removes the most recently added instance of the
ClassFileTransformer object from the VM's list of
registered transformers. |
| addTransformer | | public void addTransformer(ClassFileTransformer transformer)(Code) | | 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. |
| getAllLoadedClasses | | public Class[] getAllLoadedClasses()(Code) | | Returns an array of all of the classes that have been loaded into the VM.
an array of Class objects with each elementidentifying a class that has been loaded into the VM. |
| getInitiatedClasses | | public Class[] getInitiatedClasses(ClassLoader loader)(Code) | | 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 classesinitiated by the bootstrap class loader this argument shouldbe null. an array of Class objects with each elementidentifying a class that has been initiated by the specifiedclass loader. |
| getObjectSize | | public long getObjectSize(Object objectToSize)(Code) | | 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 an approximation of the number of bytes in memory taken up byobjectToSize.
throws:
NullPointerException - if the given object is null. |
| isRedefineClassesSupported | | public boolean isRedefineClassesSupported()(Code) | | Returns a boolean indication of whether or not this VM supports the
on-the-fly redefining of classes that have been already loaded.
true if class redefining is supported, otherwisefalse. |
| redefineClasses | | public void redefineClasses(ClassDefinition[] definitions) throws ClassNotFoundException, UnmodifiableClassException(Code) | | 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:
- attributes
- constant pool
- method implementations
If any invocations of a redefined method are already active in the VM
when this call is made then they will run to completion and be unaffected
by the outcome of this method. Provided the method redefinition is
successful, all subsequent calls on the method will run the new version.
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 wrappingthe details of the classes to be redefined. A zero-lengtharray value will not cause an error but, instead, willsilently do nothing.
throws:
ClassNotFoundException - if any of the classes specified in the contents ofdefinitions cannot be located.
throws:
UnmodifiableClassException - if any of the classes specified in the contents ofdefinitions cannot be modified.
throws:
UnsupportedOperationException - if this method is not supported in by the VM. May be checkedin advance by calling Instrumentation.isRedefineClassesSupported().
throws:
ClassFormatError - if any of the definitions elements has beencreated with a byte array containing a badlyformed class file.
throws:
NoClassDefFoundError - if there is disagreement between the name of a class to beredefined and the name of the class from the correspondingclass file format byte array.
throws:
UnsupportedClassVersionError - if the version of any of the classes to be redefined is notsupported by the VM.
throws:
ClassCircularityError - if a circular dependency is detected among the classes to beredefined.
throws:
LinkageError - if a linkage error situation is detected such that there isan incompatability between dependent classes.
throws:
NullPointerException - if definitions or any of its elements arefound to be null.
See Also: Instrumentation.isRedefineClassesSupported() |
| removeTransformer | | public boolean removeTransformer(ClassFileTransformer transformer)(Code) | | 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. true if transformer was located inthe list of registered transformers and successfully removed.Otherwise, false.
throws:
NullPointerException - if transformer is null. |
|
|
|