JavaTM 2 Platform
Standard Ed. 5.0

java.lang.instrument
接口 Instrumentation


public interface Instrumentation

此类提供检测 Java 编程语言代码所需的服务。检测是向方法中添加字节码,其目的是获取各种工具所使用的数据。由于更改完全是进行添加,所以这些工具不修改应用程序的状态或行为。此类优秀工具的例子包括镜像代理、分析器、覆盖分析器和事件记录器。

访问 Instrumentation 接口实例的惟一方法是以指示代理类的方式启动 JVM - 请参阅 包规范Instrumentation 实例被传递给代理类的 premain 方法。如果某个代理程序获得了 Instrumentation 实例,它便可以在任何时间调用该实例上的方法。

从以下版本开始:
JDK1.5

方法摘要
 void addTransformer(ClassFileTransformer transformer)
          注册提供的转换器。
 Class[] getAllLoadedClasses()
          返回当前由 JVM 加载的所有类的数组。
 Class[] getInitiatedClasses(ClassLoader loader)
          返回所有类的数组,loader 是类的初始化加载器。
 long getObjectSize(Object objectToSize)
          返回指定对象使用的特定于实现的存储量的近似值。
 boolean isRedefineClassesSupported()
          返回当前 JVM 配置是否支持类的重定义。
 void redefineClasses(ClassDefinition[] definitions)
          使用提供的类文件重定义提供的类集。
 boolean removeTransformer(ClassFileTransformer transformer)
          注销提供的转换器。
 

方法详细信息

addTransformer

void addTransformer(ClassFileTransformer transformer)
注册提供的转换器。以后的所有类定义都可以通过转换器看到,但所有已注册的转换器所依赖的类定义除外。如果注册了多个转换器,那么会按添加的顺序调用它们。如果转换器在执行期间抛出异常,则 JVM 仍将按顺序调用其他已注册的转换器。可以多次添加同一转换器。在任何外部 JVMTI ClassFileLoadHookAll 事件监听器看到类文件之前,用 addTransformer 注册的所有转换器始终可以看到类文件。

此方法旨在用于检测,如类规范中所述。

参数:
transformer - 要注册的转换器
抛出:
NullPointerException - 如果传递了一个 null 转换器

removeTransformer

boolean removeTransformer(ClassFileTransformer transformer)
注销提供的转换器。以后的类定义将不显示给该转换器。移除最近添加的转换器的匹配实例。由于类加载的多线程特性,在调用被移除后,转换器还可能接收调用。所以编写的转换器应防止出现这种情况。

参数:
transformer - 要注销的转换器
返回:
如果找到并移除转换器,则返回 true;如果找不到转换器,则返回 false
抛出:
NullPointerException - 如果传递了一个 null 转换器

isRedefineClassesSupported

boolean isRedefineClassesSupported()
返回当前 JVM 配置是否支持类的重定义。重定义已加载类的能力是 JVM 的一个可选功能。在执行单个 JVM 的单实例化过程中,对此方法的多个调用将始终返回同一应答。

返回:
如果当前 JVM 配置支持类的重定义,则为 true,否则为 false。
另请参见:
redefineClasses(java.lang.instrument.ClassDefinition[])

redefineClasses

void redefineClasses(ClassDefinition[] definitions)
                     throws ClassNotFoundException,
                            UnmodifiableClassException
使用提供的类文件重定义提供的类集。对集合进行操作,以允许同时对多个类进行互锁定更改(重定义类 A 要求重定义类 B)。

如果重定义的方法有活动的堆栈帧,则这些活动的帧会继续运行初始方法的字节码。将在新的调用上使用此重定义的方法。

此方法不会导致任何初始化(除非它发生在自定义 JVM 语义中)。换句话说,重定义类不会导致其初始化程序运行。静态变量的值将保持为该调用之前的值。

重定义类的实例不受影响。

已注册的转换器在应用重定义操作之前将被调用。

该重定义可以更改方法体、常量池和属性。该重定义不能添加、移除或重命名字段或方法、更改方法签名或者更改继承。以后的版本可能会去掉这些限制。

允许零长度 definitions 数组,在这种情况下,此方法不执行任何操作。

如果此方法抛出异常,则不会重定义任何类。

此方法旨在用于检测,如 类规范 中的描述。

参数:
definitions - 要使用相应定义来进行重定义的类的数组
抛出:
ClassNotFoundException - 如果找不到指定的类
UnmodifiableClassException - 如果无法修改指定的类
UnsupportedOperationException - 如果 JVM 的当前配置不允许重定义(isRedefineClassesSupported() 为 false)或重定义做了不支持的更改
ClassFormatError - 如果数据不包含有效类
NoClassDefFoundError - 如果类文件中的名称与类名称不相等
UnsupportedClassVersionError - 如果类文件版本号不受支持
ClassCircularityError - 如果新类包含循环
LinkageError - 如果发生链接错误
NullPointerException - 如果提供的定义数组或其任何组件为 null
另请参见:
isRedefineClassesSupported(), addTransformer(java.lang.instrument.ClassFileTransformer), ClassFileTransformer

getAllLoadedClasses

Class[] getAllLoadedClasses()
返回当前由 JVM 加载的所有类的数组。

返回:
包含由 JVM 加载的所有类的数组,如果没有,则返回长度为零的数组

getInitiatedClasses

Class[] getInitiatedClasses(ClassLoader loader)
返回所有类的数组,loader 是类的初始化加载器。如果提供的加载器为 null,则返回由引导类加载器初始化的类。

参数:
loader - 将返回其初始化类列表的加载器
返回:
包含所有类的数组,加载器是该类的初始加载器,如果没有,则返回长度为零的数组

getObjectSize

long getObjectSize(Object objectToSize)
返回指定对象使用的特定于实现的存储量的近似值。该结果可能包括对象的部分或全部开销,因此,在一个实现中进行比较时较为有用,但不能用于实现之间的比较。 该估计值在 JVM 的单一调用期间可能发生变化。

参数:
objectToSize - 需要确定大小的对象
返回:
指定对象使用的特定于实现的存储量的近似值
抛出:
NullPointerException - 如果提供的 Object 参数为 null

JavaTM 2 Platform
Standard Ed. 5.0

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

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