java.lang.instrument
public interface
public interface
java.lang.instrument.ClassFileTransformer
| java.lang.instrument.ClassFileTransformer |
This interface must be implemented by types used to instrument classes as
they are loaded by a running VM. Implementations are registered by agents in
the addTransformer(ClassFileTransformer) operation.
Once registered, a ClassFileTransformer has the opportunity to
instrument every class that is loaded or redefined by the VM provided that
the transformer does not have a dependency on that class.
Transformations of classes takes place just prior to them being defined by the VM.
Summary
Public Methods
| byte[] | transform(ClassLoader loader, String className, Class classBeingRedefined, ProtectionDomain protectionDomain, byte[] classfileBuffer) | ||||
Receives a byte array containing the raw contents of a
class for possible transformation into a new byte
array which gets returned to the caller. |
|||||
Details
Public Methods
public byte[] transform(ClassLoader loader, String className, Class classBeingRedefined, ProtectionDomain protectionDomain, byte[] classfileBuffer)
Receives a
byte array containing the raw contents of a
class for possible transformation into a new byte
array which gets returned to the caller. It is left up to the
implementation to decide what, if any, transformations are carried out
and returned.
Requests for class transformations can occur in two situations.
- the attempted defining of a class using defineClass(java.lang.String, byte[], int, int)
- the attempted re-defining of a previously defined class using redefineClasses(ClassDefinition[])
Class file format. Each
registered ClassFileTransformer instance will have this
operation called on it. The order of the invocations matches the order in
which the transformers were registered using the method
addTransformer(ClassFileTransformer).
Provided that the implementation of this method wishes to carry out a
transformation, the return is a newly allocated byte array
which contains a copy of the classfileBuffer
argument plus the transformations to the array specific to the method
implementation. If the transformer is written so as to pass on the
opportunity to modify a given input then the return value should be
null.
Parameters
| loader | the defining ClassLoader for the
candidate class to be transformed. |
|---|---|
| className | the fully qualified name of the candidate class to be transformed in the fully/qualified/Name format. |
| classBeingRedefined | if a class redefinition is in process then this argument will
be the Class object for the class. Otherwise,
if a class definition is in process, a null. |
| protectionDomain | the security protection domain for the class being defined or redefined. |
| classfileBuffer | a byte array containing the class to be
transformed in Class file format.
This argument
must not be modified. |
Returns
- if transformation occurs, a newly allocated
bytearray containing the modified version ofclassfileBuffer, otherwisenull.
Throws
| IllegalClassFormatException | if the classfileBuffer does not contain a
well-formed representation of a class in the
Class file format. Note that if an invocation
of this operation ends on an exception throw then (a) the
remaining transformers in the "chain" will still
have this method called, and (b) the class definition or
redefinition that was the catalyst for the transformation
opportunities will still be attempted.
|
|---|