JavaTM 2 Platform
Standard Ed. 5.0

java.lang.instrument
接口 ClassFileTransformer


public interface ClassFileTransformer

代理提供此接口的实现,以便转换类文件。在 JVM 定义类之前发生转换。

注意,按《The Java Virtual Machine Specification》的 The class File Format 一章中定义的方式使用术语类文件,它指的是以类文件格式表示的字节序列,无论该序列是否驻留于文件中。

从以下版本开始:
JDK1.5
另请参见:
Instrumentation, Instrumentation.addTransformer(java.lang.instrument.ClassFileTransformer), Instrumentation.removeTransformer(java.lang.instrument.ClassFileTransformer)

方法摘要
 byte[] transform(ClassLoader loader, String className, Class<?> classBeingRedefined, ProtectionDomain protectionDomain, byte[] classfileBuffer)
          实现此方法可以转换提供的类文件,并返回一个新的替换类文件。
 

方法详细信息

transform

byte[] transform(ClassLoader loader,
                 String className,
                 Class<?> classBeingRedefined,
                 ProtectionDomain protectionDomain,
                 byte[] classfileBuffer)
                 throws IllegalClassFormatException
实现此方法可以转换提供的类文件,并返回一个新的替换类文件。

在转换器利用 Instrumentation.addTransformer 注册之后,在定义每个新类和重定义每个类时都将调用该转换器。对新的类定义的请求通过 ClassLoader.defineClass 进行。对类重定义的请求通过 Instrumentation.redefineClasses 或其本机等效方法进行。转换器是在验证或应用类文件字节之前的处理请求过程中进行调用的。

如果实现方法确定不需要进行转换,则将返回 null。否则,它将创建一个新的 byte[] 数组,将输入 classfileBuffer 连同所有需要的转换复制到其中,并返回新数组。不得修改输入 classfileBuffer

在重定义情形中,转换器必须支持重定义语义。如果转换器在最初定义期间更改的类在以后要重定义,转换器必须确保第二个输出类文件是第一个输出类文件的合法重定义文件。

如果转换器认为 classFileBuffer 不表示一个有效格式的类文件,则将抛出 IllegalClassFormatException。随后仍将调用转换器,而且仍将尝试加载或重定义。因此,抛出 IllegalClassFormatException 与返回 null 具有相同的效果,但前者便于对格式毁坏进行记录或调试。

参数:
loader - 定义要转换的类加载器,如果是引导加载器则可以为 null
className - 完全限定的类的内部形式中的类名称和 The Java Virtual Machine Specification 中定义的接口名称。例如,"java/util/List"
classBeingRedefined - 如果是重定义,则为要重定义的类,否则为 null
protectionDomain - 要定义或重定义的类的保护域
classfileBuffer - 类文件格式的输入字节缓冲区(不得修改)
返回:
一个格式良好的类文件缓冲区(转换的结果),如果未执行转换,则返回 null
抛出:
IllegalClassFormatException - 如果输入不表示一个格式良好的类文件
另请参见:
Instrumentation.redefineClasses(java.lang.instrument.ClassDefinition[])

JavaTM 2 Platform
Standard Ed. 5.0

提交错误或意见
有关更多的 API 参考资料和开发人员文档,请参阅 Java 2 SDK SE 开发人员文档。该文档包含更详细的、面向开发人员的描述,以及总体概述、术语定义、使用技巧和工作代码示例。

版权所有 2004 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策