compact3

Package java.lang.instrument

提供的服务允许java编程语言的代理工具运行在JVM上的程序。

See: 描述

接口摘要

接口	描述
ClassFileTransformer	代理提供此接口的实现，以转换类文件。
Instrumentation	这个类提供了所需的工具java编程语言代码服务。

类摘要

类	描述
ClassDefinition	这类作为一个参数块的 Instrumentation.redefineClasses方法。

异常摘要

异常	描述
IllegalClassFormatException	扔的 ClassFileTransformer.transform实现当输入参数无效。
UnmodifiableClassException	扔的 Instrumentation.redefineClasses实现当一个指定的类不能被修改。

Package java.lang.instrument Description

提供的服务允许java编程语言的代理工具运行在JVM上的程序。仪器的机制是修改的字节码的方法。

包装规格

一个代理被部署为一个文件。在“罐子”文件清单中的一个属性指定将被加载到启动代理的代理类。对于支持命令行界面的实现，通过在命令行上指定一个选项来启动代理程序。实现也可以支持一个机制，开始代理一些时间后，虚拟机已经开始。例如，一个实现可能提供了一种机制，允许一个工具零贴上到运行的应用程序，并启动该工具的代理加载到运行的应用程序。有关如何启动负载的详细信息，是依赖于实现的。

命令行界面

不需要一个实现，以提供一种从命令行界面开始代理的方法。在提供了从命令行界面开始代理的方法的实现中，一个代理是通过将此选项添加到命令行启动的开始的：

-javaagent: jarpath[ = options]

nulljarpath是代理JAR文件的路径。空选项是代理人的选择。此开关可以在同一个命令行上多次使用，从而创建多个代理。多个代理可以使用相同的nulljarpath。一个代理的“文件”文件必须符合“文件规范”的文件规范。

代理人的JAR文件的清单必须包含属性Premain-Class。此属性的值是零代理类名称。代理类必须实现原理上类似于main程序入口点premain公共静态方法。java虚拟机（JVM）初始化后，每个premain方法将顺序指定代理商，那么真正的应用main方法会被调用。每个premain方法必须返回为了启动顺序进行。

premain的方法有两种可能的签名。JVM首先尝试调用代理类的方法如下：

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

如果代理类不实现这个方法，那么JVM将尝试调用：

public static void premain(String agentArgs);

代理类会使用agentmain方法当代理在虚拟机启动开始。当代理开始使用命令行选项的agentmain方法不会被调用。

代理类将被系统类加载器加载（见ClassLoader.getSystemClassLoader）。这是类加载器通常负载包含应用程序main方法的类。的premain方法将运行在相同的安全和运行规则的应用main方法。没有限制的代理premain建模方法可以做什么。任何应用main可以做，包括创建线程，是法律从premain。

各代理商通过其代理人通过agentArgs参数选项。代理选项作为一个单一的字符串传递，任何附加的分析都应该由代理本身执行。

如果代理人不能得到解决（例如，因为代理类不能被加载，或因为代理类没有一个合适的premain法），JVM将中止。如果一个premain方法抛出未捕获的异常，JVM将中止。

启动虚拟机启动后的启动代理

一个实现可能会提供一个机制来启动代理的某个时候，虚拟机已经开始。细节如何这是启动实施特定的通常的应用已经起步， main方法已经被调用。在实现支持启动虚拟机启动代理的情况下，已经开始以下应用：

1. 代理人的JAR清单必须包含属性Agent-Class。这个属性的值是零代理类名称。

2. 代理类必须实现一个公共静态agentmain方法。

3. 系统类加载器（ClassLoader.getSystemClassLoader）必须支持一种机制来添加一个代理JAR文件到系统类路径。

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

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

如果代理类不实现这个方法，那么JVM将尝试调用：

public static void agentmain(String agentArgs);

代理类会使用premain方法当代理开始使用命令行选项。当代理的虚拟机启动的premain方法不会被调用后开始。

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

的agentmain方法应该需要启动代理的任何必要的初始化。当启动完成时该方法应该返回。如果代理人不能启动（例如，因为代理类不能被加载，或因为代理类没有一致性agentmain法），JVM不会中止。如果agentmain方法抛出未捕获的异常会被忽略。

z-f9195075-b40b-453f—8b2e-c6267c5204d1以下清单属性为代理JAR文件定义：

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.

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.

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.

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.

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.

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.

代理JAR文件既有可能Premain-Class和Agent-Class属性出现在清单。当代理开始在命令行使用-javaagent选项然后Premain-Class属性指定的代理类和Agent-Class属性的名称被忽略。同样，如果代理一段时间后，虚拟机已经开始启动，然后Agent-Class属性指定代理类的名字（的Premain-Class属性的值被忽略）。

相关文件

工具文档，请参阅：

• JDK Tools and Utilities

从以下版本开始：

JDK1.5