The implementation of this method may transform the supplied class file and return a new replacement class file.
Once a transformer has been registered with {@link java.lang.instrument.Instrumentation#addTransformer Instrumentation.addTransformer}, the transformer will be called for every new class definition and every class redefinition. The request for a new class definition is made with {@link ClassLoader#defineClass ClassLoader.defineClass}. The request for a class redefinition is made with {@link java.lang.instrument.Instrumentation#redefineClasses Instrumentation.redefineClasses}or its native equivalents. The transformer is called during the processing of the request, before the class file bytes have been verified or applied.
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 redefine case, the transformer must support the redefinition semantics. If a class that the transformer changed during initial definition is later 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 believes the
classFileBuffer
does not represent a validly formatted class file, it should throw an
IllegalClassFormatException
. Subsequent transformers will still be called and the load or redefine will still be attempted. Throwing an
IllegalClassFormatException
thus has the same effect as returning null but facilitates the logging or debugging of format corruptions.
@param originalLoader 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 a redefine, the class being redefined,otherwise
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
@return a well-formed class file buffer (the result of the transform),or
null
if no transform is performed.
@throws java.lang.instrument.IllegalClassFormatException if the input does not represent a well-formed class file
@see java.lang.instrument.Instrumentation#redefineClasses