java.lang.instrument文档翻译

最新推荐文章于 2023-09-20 18:01:03 发布

ProLayman

最新推荐文章于 2023-09-20 18:01:03 发布

阅读量274

点赞数

分类专栏： Java文档阅读和翻译文章标签： Java文档翻译 instrument文档

本文链接：https://blog.csdn.net/ProLayman/article/details/112515981

版权

Java文档阅读和翻译专栏收录该内容

4 篇文章 0 订阅

订阅专栏

原文：Package java.lang.instrument

Package java.lang.instrument

java.lang.instrument包提供这样的服务：允许Java编程语言agents去instrument运行在JVM上的程序。

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

See: Description

接口概览（Interface Summary）
Interface	Description
ClassFileTransformer	一个实现此接口的代理可以transform类文件（An agent provides an implementation of this interface in order to transform class files.）
Instrumentation	这个类提供了instrument Java编程语言代码的服务（This class provides services needed to instrument Java programming language code.）

类概览（Class Summary）
Class	Description
ClassDefinition	这个类servers as `Instrumentation.redefineClasses` method的参数块（This class serves as a parameter block to the `Instrumentation.redefineClasses` method.）

异常概览（Exception Summary）
Exception	Description
IllegalClassFormatException	（当输入参数不合法时抛出，by `ClassFileTransformer.transform 的实现者）`Thrown by an implementation of `ClassFileTransformer.transform` when its input parameters are invalid.
UnmodifiableClassException	（当特定的类不能被修改时抛出，by `Instrumentation.redefineClasses` 的实现者`）`Thrown by an implementation of `Instrumentation.redefineClasses` when one of the specified classes cannot be modified.

Package java.lang.instrument Description

提供这样的服务：允许Java编程语言agents去instrument运行在JVM上的程序。instrumentation的机制是修改方法的字节码（来实现的）。

（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.）

包规范（Package Specification）

一个agent作为一个JAR文件被部署。JAR文件中的manifest属性指定了代理类（agent class），它将被加载去启动代理。在具体实现中，支持命令行接口，通过在命令行中指定一个option就可以启动一个agent。另外，同样支持JVM启动之后启动agent的机制。例如，允许attach一个工具（tool）到一个正在运行的application上，and初始化工具的agent，将其装载（load）进正在运行的application上。至于load是如何被初始化的的细节，与实现是独立的（dependent）。

（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.）

命令行交互页面（Command-Line Interface）

如果用命令行交互页面来实现，agent是通过在命令行中添加option来启动的：

（On implementations with a command-line interface, an agent is started by adding this option to the command-line:）

-javaagent: jarpath[ = options]

jarpath是agent的JAR 文件. options是agent的options. 这个switch可以在同一个命令行中多次使用。多个agent可以使用同一个jarpath. agent的JAR文件必须符合JAR文件规范（JAR file specificatio）。

agent的JAR文件中的nanifesst必须包含 Premain-Class属性. 此属性的值和agent类的名称相同。agent类必须实现一个同main方法入口类似的public static premain方法。在JVM初始化完成后，premain方法将按照指定agent时的顺序（命令行指定多个agent时）被调用,之后，应用的main方法才被调用。每个premain方法必须return，这样后续的startup才能继续。

（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.

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.）

premain方法有两个可能的签名（signature）。JVM首先尝试invoke agent类的以下方法：

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

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

如果agent类没有实现以上方法，JVM将会尝试invoke以下方法：

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

public static void premain(String agentArgs);

agent类也可以拥有agentmain方法，这个方法在VM已经启动后再去启动agent时使用。当使用命令行启动agent时，agentmain方法没有被invoked。

agent类将会被系统类加载器（system class loader）加载（见 ClassLoader.getSystemClassLoader）。应用的main方法通常就是用系统类加载器加载的。premain方法将会在同main方法相同的安全（security ）和加载器规则（classloader rules）下运行。对于premain方法的行为没有作固定的限制。任何main方法能做的，包括创建线程等，premain都可以做。

每个agent通过agentArgs参数传递options，agent options被作为单个字符串传递，任何额外的解析都应该有agent自己来完成。

如果一个agent不能被解析（resolved）（例如，由于agent类没有被装载（loaded），或者agent类没有一个合法的premain方法等原因），JVM将会中止（abort）该agent。如果一个premain方法抛出了未被捕获的异常（uncaught exception），JVM也将中止（abort）。

（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.

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.

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.

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.）

在虚拟机启动之后启动agent（Starting Agents After VM Startup）

现有机制：在虚拟机已经启动（Startup）一段时间之后，启动agents。至于启动（Starrtup）到了具体什么阶段视实际情况而定，但是通常而言指的是，应用已经started，其main方法已经被invoked。

如果实现支持在VM启动后启动代理，则适用以下情况：

agent的JAR文件的manifest必须包含Agent-Class属性，此属性的值和agent类的名称相同。
agent类必须实现public static agentmain方法.
系统类加载器（system class loader） ( ClassLoader.getSystemClassLoader) 必须支持向系统class path中添加agent JAR文件的机制。must support a mechanism to add an agent JAR file to the system class path.

（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:

The manifest of the agent JAR must contain the attribute Agent-Class. The value of this attribute is the name of the agent class.
The agent class must implement a public static agentmain method.
The system class loader ( ClassLoader.getSystemClassLoader) must support a mechanism to add an agent JAR file to the system class path.）

agent JAR被追加（append）到系统class path中，类加载器通常加载了包含main方法的类。而agent类被加载，JVM将会尝试invoke agentmain方法.JVM首先尝试invoke agent类的以下方法：

（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:）

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

如果agent类没有实现以上方法，JVM将会尝试invoke以下方法：

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

public static void agentmain(String agentArgs);

当agent已经启动，agent类仍然使用命令行来使用premain方法。当VM启动之后再启动agent，premain方法不会被invoke。

agent通过agentArgs参数传递options，agent options被作为单个字符串传递，任何额外的解析都应该有agent自己来完成。

agentmain方法应该完成启动agent所需的所有必要初始化工作。当初始化完成，方法应该return。如果agent无法启动（例如，有由于agent类没有被装载，或者因为agent类没有合法的agentmain方法），JVM将不会中止（abort）。

如果agentmain方法抛出了未捕获的异常（uncaught exception），将会被忽略。

（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.

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.

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.）

Manifest属性（Manifest Attributes）

agent JAR文件中可定义的manifest属性如下：

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

Premain-Class

当JVM启动时(JVM launch time)指定代理时，这个属性用于指定代理类（agent类）。就是说，这个类包含了premain方法。如果JVM启动时(JVM launch time)指定代理，那么这个属性是必须的（required），如果此属性缺失，JVM将中止。注意：这是一个类名，不是一个文件或路径。

（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.）

Agent-Class

如果实现支持在VM启动后的某个时间启动代理的机制，则此属性指定代理类。就是说，这个类包含了agentmain方法，则这个属性是必须的。如果这个属性缺失，那么agent将不会被启动。

注意：这是一个类名，不是一个文件或路径。

（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.）

Boot-Class-Path

将会被bootstrap类加载器搜索的路径清单。每个路径代表着目录或libraries（通常指的是各种平台的JAR或者zip libraries）。在特定平台定位类（locate class）的机制失败后，bootstrap类将按照清单上的顺序依次搜索这些路径。

清单上的路径用一个或多个空格分开，路径采用层次URI的路径组件的语法，以'/'开头的路径将会被视为绝对路径，除此之外将会被视为相对路径。相对路径的根目录是agent类JAR文件所在的路径。不合法和不存在的路径将会被忽略。如果虚拟机

启动后的某个时间点启动agent，那些非JAR路径将会被忽略。这个属性是可选的（optional）。

（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.）

Can-Redefine-Classes

Boolean (true or false, 大小写不敏感)。能否redefine类. 除去true之外值都将被看作false。这个属性是可选的（optional）。默认值是false.

（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.）

Can-Retransform-Classes

Boolean (true or false, 大小写不敏感)。能否retransform类. 除去true之外值都将被看作false。这个属性是可选的（optional）。默认值是false.

（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.）

Can-Set-Native-Method-Prefix

Boolean (true or false, 大小写不敏感)。能否设置native方法前缀。除去true之外值都将被看作false。这个属性是可选的（optional）。默认值是false.

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.

agent JAR文件中manifest可以同时拥有Premain-Class和Agent-Class属性。当使用命令行使用-javaagent命令启动agent时，由Premain-Class属性指定agent类的名称，而Agent-Class属性将会被忽略。相似地，如果agent在虚拟机启动后的某个时间被启动，那么由Agent-Class属性确定agent类的名称，Premain-Class属性值将会被忽略。

（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).）