/* * @(#)ClassFileTransformer.java 1.5 04/05/05 * * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms. */ package java.lang.instrument; import java.security.ProtectionDomain; /* * Copyright 2003 Wily Technology, Inc. */ /** * An agent provides an implementation of this interface in order * to transform class files. * The transformation occurs before the class is defined by the JVM. *
* Note the term class file is used as defined in the chapter * The class File Format * of The Java Virtual Machine Specification, to mean a sequence * of bytes in class file format, whether or not they reside in a file. * * @see java.lang.instrument.Instrumentation * @see java.lang.instrument.Instrumentation#addTransformer * @see java.lang.instrument.Instrumentation#removeTransformer * @since JDK1.5 */ public interface ClassFileTransformer { /** * 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 java.lang.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 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 fully
* qualified 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
*
* @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
*/
byte[]
transform( ClassLoader loader,
String className,
Class> classBeingRedefined,
ProtectionDomain protectionDomain,
byte[] classfileBuffer)
throws IllegalClassFormatException;
}