java.lang.Instrument包规范说明（中英双文）——2021-8-11

Package java.lang.instrument

Provides services that allow Java programming language agents to instrument programs running on the JVM.

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

Interface	Description
ClassFileTransformer	An agent provides an implementation of this interface in order to transform class files. 代理提供此接口的实现以转换类文件。
Instrumentation	This class provides services needed to instrument Java programming language code. 此类提供检测 Java 编程语言代码所需的服务。

Class	Description
ClassDefinition	This class serves as a parameter block to the Instrumentation.redefineClasses method. 此类用作 Instrumentation.redefineClasses 方法的参数块。

Exception	Description
IllegalClassFormatException	Thrown by an implementation of ClassFileTransformer.transform when its input parameters are invalid. 当 ClassFileTransformer.transform 的输入参数无效时，由它的实现抛出。
UnmodifiableClassException	Thrown by an implementation of Instrumentation.redefineClasses when one of the specified classes cannot be modified. 当指定的类之一无法修改时，由 Instrumentation.redefineClasses 的实现抛出。

Package java.lang.instrument Description

Provides services that allow Java programming language agents to instrument programs running on the JVM. The mechanism for instrumentation is modification of the byte-codes of methods.

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

Package Specification 包规范、规格

An agent is deployed as a JAR file. An attribute in the JAR file manifest specifies the agent class which will be loaded to start the agent. For implementations that support a command-line interface, an agent is started by specifying an option on the command-line. Implementations may also support a mechanism to start agents some time after the VM has started. For example, an implementation may provide a mechanism that allows a tool to attach to a running application, and initiate the loading of the tool’s agent into the running application. The details as to how the load is initiated, is implementation dependent.

代理部署为 JAR 文件。 JAR 文件清单中的属性指定将加载以启动代理的代理类。 对于支持命令行界面的实现，通过在命令行上指定一个选项来启动代理。 实现也可能支持在 VM 启动一段时间后启动代理的机制。 例如，实现可以提供一种机制，允许工具附加到正在运行的应用程序，并启动将工具的代理加载到正在运行的应用程序中。 关于如何启动加载的细节，实现是依赖的。

Command-Line Interface

An implementation is not required to provide a way to start agents from the command-line interface. On implementations that do provide a way to start agents from the command-line interface, an agent is started by adding this option to the command-line:

-javaagent:jarpath[=options]

jarpath is the path to the agent JAR file. options is the agent options. This switch may be used multiple times on the same command-line, thus creating multiple agents. More than one agent may use the same jarpath. An agent JAR file must conform to the JAR file specification.

实现不需要提供从命令行界面启动代理的方法。 在确实提供从命令行界面启动代理的方法的实现上，通过向命令行添加此选项来启动代理：

-javaagent: jarpath [= 选项]
jarpath 是代理 JAR 文件的路径。 options 是代理选项。 此开关可以在同一命令行上多次使用，从而创建多个代理。 多个代理可能使用相同的 jarpath。 代理 JAR 文件必须符合 JAR 文件规范。

The manifest of the agent JAR file must contain the attribute Premain-Class. The value of this attribute is the name of the agent class. The agent class must implement a public static premain method similar in principle to the main application entry point. After the Java Virtual Machine (JVM) has initialized, each premain method will be called in the order the agents were specified, then the real application main method will be called. Each premain method must return in order for the startup sequence to proceed.

代理 JAR 文件的清单必须包含属性 premain 类。 该属性的值是代理类的名称。 代理类必须实现一个与主应用程序入口点原则相似的公共静态 premain 方法。 在 Java 虚拟机 (JVM) 初始化后，将按照指定代理的顺序调用每个 premain 方法，然后将调用真正的应用程序 main 方法。 每个 premain 方法都必须返回，以便启动序列继续进行。

The premain method has one of two possible signatures. The JVM first attempts to invoke the following method on the agent class:

premain 方法具有两个可能的签名之一。 JVM 首先尝试在代理类上调用以下方法：

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

If the agent class does not implement this method then the JVM will attempt to invoke:

如果代理类未实现此方法，则 JVM 将尝试调用：

public static void premain(String agentArgs);

The agent class may also have an agentmain method for use when the agent is started after VM startup. When the agent is started using a command-line option, the agentmain method is not invoked.

agent 类也可能有一个 agentmain 方法，用于在 VM 启动后启动代理时使用。当使用命令行选项启动代理时，不会调用代理 agentmain 方法。

The agent class will be loaded by the system class loader (see ClassLoader.getSystemClassLoader). This is the class loader which typically loads the class containing the application main method. The premain methods will be run under the same security and classloader rules as the application main method. There are no modeling restrictions on what the agent premain method may do. Anything application main can do, including creating threads, is legal from premain.

代理类将由系统类加载器加载（请参阅 ClassLoader.getSystemClassLoader）。这是类加载器，它通常加载包含应用程序 main 方法的类。 premain 方法将在与应用程序 main 方法相同的安全性和类加载器规则下运行。代理 premain 方法可以做什么没有建模限制。应用程序 main 可以做的任何事情，包括创建线程，在 premain 中都是合法的。

Each agent is passed its agent options via the agentArgs parameter. The agent options are passed as a single string, any additional parsing should be performed by the agent itself.

每个代理都通过 agentArgs 参数传递其代理选项。代理选项作为单个字符串传递，任何额外的解析都应该由代理本身执行。

If the agent cannot be resolved (for example, because the agent class cannot be loaded, or because the agent class does not have an appropriate premain method), the JVM will abort. If a premain method throws an uncaught exception, the JVM will abort.

如果无法解析代理（例如，无法加载代理类，或者代理类没有合适的 premain 方法），JVM 将中止。如果 premain 方法抛出未捕获的异常，JVM 将中止。

Starting Agents After VM Startup

An implementation may provide a mechanism to start agents sometime after the the VM has started. The details as to how this is initiated are implementation specific but typically the application has already started and its main method has already been invoked. In cases where an implementation supports the starting of agents after the VM has started the following applies:

一个实现可能会提供一种机制来在 VM 启动后的某个时间启动代理。关于如何启动的细节是特定于实现的，但通常应用程序已经启动并且它的主要方法已经被调用。如果实现支持在 VM 启动后启动代理，则以下适用：

1. The manifest of the agent JAR must contain the attribute Agent-Class. The value of this attribute is the name of the agent class. 代理 JAR 的清单必须包含Agent-Class属性。该属性的值是代理类的名称。

2. The agent class must implement a public static agentmain method. 代理类必须实现公共静态代理 main 方法。

3. The system class loader ( ClassLoader.getSystemClassLoader) must support a mechanism to add an agent JAR file to the system class path. 系统类加载器 (ClassLoader.getSystemClassLoader) 必须支持将代理 JAR 文件添加到系统类路径的机制。

The agent JAR is appended to the system class path. This is the class loader that typically loads the class containing the application main method. The agent class is loaded and the JVM attempts to invoke the agentmain method. The JVM first attempts to invoke the following method on the agent class:

代理 JAR 附加到系统类路径。这是通常加载包含应用程序 main 方法的类的类加载器。加载代理类，JVM 尝试调用agentmain方法。 JVM 首先尝试在代理类上调用以下方法：

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

If the agent class does not implement this method then the JVM will attempt to invoke:

public static void agentmain(String agentArgs);

The agent class may also have an premain method for use when the agent is started using a command-line option. When the agent is started after VM startup the premain method is not invoked.

当使用命令行选项启动代理时，代理类也可能有一个 premain 方法。 在 VM 启动后启动代理时，不会调用 premain 方法。

The agent is passed its agent options via the agentArgs parameter. The agent options are passed as a single string, any additional parsing should be performed by the agent itself.

代理通过 agentArgs 参数传递其代理选项。 代理选项作为单个字符串传递，任何额外的解析都应该由代理本身执行。

The agentmain method should do any necessary initialization required to start the agent. When startup is complete the method should return. If the agent cannot be started (for example, because the agent class cannot be loaded, or because the agent class does not have a conformant agentmain method), the JVM will not abort. If the agentmain method throws an uncaught exception it will be ignored.

agentmain 方法应执行启动代理所需的任何必要初始化。 启动完成后，该方法应返回。 如果代理无法启动（例如，因为无法加载代理类，或者因为代理类没有符合的agentmain 方法），JVM 不会中止。 如果代理 main 方法抛出未捕获的异常，它将被忽略。

Manifest Attributes

The following manifest attributes are defined for an agent JAR file:

Premain-Class

When an agent is specified at JVM launch time this attribute specifies the agent class. That is, the class containing the premain method. When an agent is specified at JVM launch time this attribute is required. If the attribute is not present the JVM will abort. Note: this is a class name, not a file name or path.

在 JVM 启动时指定代理时，此属性指定代理类。也就是说，包含 premain 方法的类。在 JVM 启动时指定代理时，此属性是必需的。如果该属性不存在，JVM 将中止。注意：这是一个类名，而不是文件名或路径。
代理类

Agent-Class

If an implementation supports a mechanism to start agents sometime after the VM has started then this attribute specifies the agent class. That is, the class containing the agentmain method. This attribute is required, if it is not present the agent will not be started. Note: this is a class name, not a file name or path.

如果实现支持在 VM 启动后某个时间启动代理的机制，则该属性指定代理类。即，包含agentmain 方法的类。此属性是必需的，如果它不存在，代理将不会启动。注意：这是一个类名，而不是文件名或路径。

Boot-Class-Path

A list of paths to be searched by the bootstrap class loader. Paths represent directories or libraries (commonly referred to as JAR or zip libraries on many platforms). These paths are searched by the bootstrap class loader after the platform specific mechanisms of locating a class have failed. Paths are searched in the order listed. Paths in the list are separated by one or more spaces. A path takes the syntax of the path component of a hierarchical URI. The path is absolute if it begins with a slash character (’/’), otherwise it is relative. A relative path is resolved against the absolute path of the agent JAR file. Malformed and non-existent paths are ignored. When an agent is started sometime after the VM has started then paths that do not represent a JAR file are ignored. This attribute is optional.

引导类加载器要搜索的路径列表。 路径代表目录或库（在许多平台上通常称为 JAR 或 zip 库）。 在定位类的平台特定机制失败后，引导类加载器会搜索这些路径。 按照列出的顺序搜索路径。 列表中的路径由一个或多个空格分隔。 路径采用分层 URI 的路径组件的语法。 如果路径以斜杠字符 (’/’) 开头，则该路径是绝对路径，否则它是相对路径。 根据代理 JAR 文件的绝对路径解析相对路径。 格式错误和不存在的路径将被忽略。 在 VM 启动后某个时间启动代理时，不代表 JAR 文件的路径将被忽略。 该属性是可选的。

Can-Redefine-Classes

Boolean (true or false, case irrelevant). Is the ability to redefine classes needed by this agent. Values other than true are considered false. This attribute is optional, the default is false.

布尔值（真或假，大小写无关）。 是否能够重新定义此代理所需的类。 true 以外的值被认为是 false。 该属性是可选的，默认为false。

Can-Retransform-Classes

Boolean (true or false, case irrelevant). Is the ability to retransform classes needed by this agent. Values other than true are considered false. This attribute is optional, the default is false.

布尔值（真或假，大小写无关）。 是否具有重新转换此代理所需的类的能力。 true 以外的值被认为是 false。 该属性是可选的，默认为false。

Can-Set-Native-Method-Prefix

Boolean (true or false, case irrelevant). Is the ability to set native method prefix needed by this agent. Values other than true are considered false. This attribute is optional, the default is false.

布尔值（真或假，大小写无关）。 是否能够设置此代理所需的本机方法前缀。 true 以外的值被认为是 false。 该属性是可选的，默认为false。

An agent JAR file may have both the Premain-Class and Agent-Class attributes present in the manifest. When the agent is started on the command-line using the -javaagent option then the Premain-Class attribute specifies the name of the agent class and the Agent-Class attribute is ignored. Similarly, if the agent is started sometime after the VM has started, then the Agent-Class attribute specifies the name of the agent class (the value of Premain-Class attribute is ignored).

代理 JAR 文件可能在清单中同时具有 Premain-Class 和 Agent-Class 属性。 当使用 -javaagent 选项在命令行上启动代理时，Premain-Class 属性指定代理类的名称，而 Agent-Class 属性将被忽略。 同样，如果代理在 VM 启动后的某个时间启动，则 Agent-Class 属性指定代理类的名称（忽略 Premain-Class 属性的值）。