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。