软件包 java.lang.instrument

提供允许 Java 编程语言代理监测运行在 JVM 上的程序的服务。

请参见：
描述

接口摘要

ClassFileTransformer	代理提供此接口的实现，以便转换类文件。
Instrumentation	此类提供检测 Java 编程语言代码所需的服务。

类摘要

ClassDefinition

此类用作 Instrumentation.redefineClasses 方法的参数锁定。

异常摘要

IllegalClassFormatException	当其输入参数无效时，由 ClassFileTransformer.transform 的实现抛出该异常。
UnmodifiableClassException	在无法修改指定类之一时，由 Instrumentation.redefineClasses 的实现抛出此异常。

软件包 java.lang.instrument 的描述

提供允许 Java 编程语言代理监测运行在 JVM 上的程序的服务。监测的机制是对方法的字节码的修改。

包规范

在启动 JVM 时，通过指示代理类 及其代理选项 启动一个代理程序。

该代理类必须实现公共的静态 premain 方法，该方法原理上类似于 main 应用程序入口点：

public static void premain(String agentArgs, Instrumentation inst);

JVM 被初始化之后，每个 premain 方法将按照指定代理的顺序被调用。然后，调用实际的应用程序 main 方法。每个 premain 方法必须按顺序返回，以便启动序列能够继续。代理类将由加载包含应用程序 main 方法的类的同一类加载器加载。premain 方法将在与应用程序 main 方法相同的安全性和类加载器规则下运行。不存在代理 premain 方法可以执行的建模限制。应用程序 main 可以执行的任何事情（包括生成线程）从 premain 来看都是合法的。

每个代理程序通过 agentArgs 参数传递其代理选项。代理选项作为单个字符串传递，任何其他分析应由代理程序本身执行。

如果该代理程序不能被解析（例如，由于无法加载代理类，或由于代理类没有一致的 premain 方法），则 JVM 将中止。如果 premain 方法抛出未捕获的异常，则 JVM 将中止。

命令行接口

在带有命令行接口的 JVM 上，通过向 JVM 命令行添加此开关来指定代理程序：

-javaagent:jarpath[=options]

jarpath 是指向代理程序 JAR 文件的路径。options 是代理选项。此开关可以在同一命令行上多次使用，从而创建多个代理程序。多个代理程序可以使用同一 jarpath。代理 JAR 文件必须符合 JAR 文件规范。下面的清单属性是针对代理 JAR 文件定义的：

Premain-Class

代理类。即包含 premain 方法的类。此属性是必需的，如果它不存在，JVM 将中止。注：这是类名，而不是文件名或路径。

Boot-Class-Path

由引导类加载器搜索的路径列表。路径表示目录或库（在许多平台上通常作为 jar 或 zip 库被引用）。查找类的特定于平台的机制出现故障之后，引导类加载器会搜索这些路径。按列出的顺序搜索路径。列表中的路径由一个或多个空格分开。路径使用分层 URI 的路径组件的语法。如果该路径以斜杠字符（“/”）开头，则为绝对路径，否则为相对路径。相对路径根据代理 JAR 文件的绝对路径解析。忽略格式不正确的路径和不存在的路径。此属性是可选的。

Can-Redefine-Classes

布尔值（true 或 false，与大小写无关）。能够重定义此代理所需的类。值如果不是 true，则被认为是 false。此属性是可选的，默认值为 false。

代理 JAR 文件附加到类路径之后。

相关文档

有关工具文档的信息，请参阅：

• JDK Tools and Utilities

从以下版本开始：

JDK1.5