There are two kinds of transformers, determined by the canRetransform
parameter of {@link java.lang.instrument.Instrumentation#addTransformer(ClassFileTransformer,boolean)}:
canRetransform
as true canRetransform
as false or where added with {@link java.lang.instrument.Instrumentation#addTransformer(ClassFileTransformer)} Once a transformer has been registered with {@link java.lang.instrument.Instrumentation#addTransformer(ClassFileTransformer,boolean) addTransformer}, the transformer will be called for every new class definition and every class redefinition. Retransformation capable transformers will also be called on every class retransformation. The request for a new class definition is made with {@link java.lang.ClassLoader#defineClass ClassLoader.defineClass}or its native equivalents. The request for a class redefinition is made with {@link java.lang.instrument.Instrumentation#redefineClasses Instrumentation.redefineClasses}or its native equivalents. The request for a class retransformation is made with {@link java.lang.instrument.Instrumentation#retransformClasses Instrumentation.retransformClasses}or its native equivalents. The transformer is called during the processing of the request, before the class file bytes have been verified or applied. When there are multiple transformers, transformations are composed by chaining the transform
calls. That is, the byte array returned by one call to transform
becomes the input (via the classfileBuffer
parameter) to the next call.
Transformations are applied in the following order:
For retransformations, the retransformation incapable transformers are not called, instead the result of the previous transformation is reused. In all other cases, this method is called. Within each of these groupings, transformers are called in the order registered. Native transformers are provided by the ClassFileLoadHook
event in the Java Virtual Machine Tool Interface).
The input (via the classfileBuffer
parameter) to the first transformer is:
ClassLoader.defineClass
definitions.getDefinitionClassFile()
where definitions
is the parameter to {@link java.lang.instrument.Instrumentation#redefineClasses Instrumentation.redefineClasses} If the implementing method determines that no transformations are needed, it should return null
. Otherwise, it should create a new byte[]
array, copy the input classfileBuffer
into it, along with all desired transformations, and return the new array. The input classfileBuffer
must not be modified.
In the retransform and redefine cases, the transformer must support the redefinition semantics: if a class that the transformer changed during initial definition is later retransformed or redefined, the transformer must insure that the second class output class file is a legal redefinition of the first output class file.
If the transformer throws an exception (which it doesn't catch), subsequent transformers will still be called and the load, redefine or retransform will still be attempted. Thus, throwing an exception has the same effect as returning null
. To prevent unexpected behavior when unchecked exceptions are generated in transformer code, a transformer can catch Throwable
. If the transformer believes the classFileBuffer
does not represent a validly formatted class file, it should throw an IllegalClassFormatException
; while this has the same effect as returning null. it facilitates the logging or debugging of format corruptions.
@param loader the defining loader of the class to be transformed,may be null
if the bootstrap loader
@param className the name of the class in the internal form of fullyqualified class and interface names as defined in The Java Virtual Machine Specification. For example, "java/util/List"
.
@param classBeingRedefined if this is triggered by a redefine or retransform, the class being redefined or retransformed; if this is a class load, null
@param protectionDomain the protection domain of the class being defined or redefined
@param classfileBuffer the input byte buffer in class file format - must not be modified
@throws IllegalClassFormatException if the input does not represent a well-formed class file
@return a well-formed class file buffer (the result of the transform), or null
if no transform is performed.
@see Instrumentation#redefineClasses
|
|
|
|
|
|
|
|
|
|
|
|
|
|