模块 jdk.attach
包 com.sun.tools.attach

类 VirtualMachine

java.lang.Object
com.sun.tools.attach.VirtualMachine
public abstract class VirtualMachine extends Object
Java 虚拟机。

VirtualMachine 表示此 Java 虚拟机已附加到的 Java 虚拟机。它所连接的 Java 虚拟机有时称为目标虚拟机， 或者目标虚拟机.应用程序（通常是管理控制台或分析器等工具）使用 VirtualMachine 将代理加载到目标 VM 中。例如，用 Java 语言编写的分析器工具可能附加到正在运行的应用程序并加载其分析器代理以分析正在运行的应用程序。

VirtualMachine 是通过使用标识目标虚拟机的标识符调用 attach 方法获得的。标识符是依赖于实现的，但在每个 Java 虚拟机在其自己的操作系统进程中运行的环境中通常是进程标识符（或 pid）。或者，通过使用从 list 方法返回的虚拟机描述符列表中获得的 VirtualMachineDescriptor 调用 attach 方法来获取 VirtualMachine 实例。一旦获得对虚拟机的引用，就会使用 loadAgent 、 loadAgentLibrary 和 loadAgentPath 方法将代理加载到目标虚拟机中。 loadAgent 方法用于加载用 Java 语言编写并部署在 JAR file 中的代理。 （有关如何加载和启动这些代理的详细说明，请参阅 java.lang.instrument ）。 loadAgentLibrary 和 loadAgentPath 方法用于加载部署在动态库中或静态链接到 VM 的代理，并使用 JVM 工具接口 。

除了加载代理之外，虚拟机还提供对目标 VM 中的system properties 的读取访问。这在某些环境中很有用，在这些环境中，诸如 java.home 、 os.name 或 os.arch 等属性用于构造将加载到目标 VM 中的代理的路径。

以下示例演示了如何使用 VirtualMachine：

   // attach to target VM
   VirtualMachine vm = VirtualMachine.attach("2177");

   // start management agent
   Properties props = new Properties();
   props.put("com.sun.management.jmxremote.port", "5000");
   vm.startManagementAgent(props);

   // detach
   vm.detach();

在此示例中，我们附加到由进程标识符 2177 标识的 Java 虚拟机。然后使用提供的参数在目标进程中启动 JMX 管理代理。最后，客户端与目标 VM 分离。

VirtualMachine 可以安全地供多个并发线程使用。

自从：
1.6

  • 构造方法详细信息

    • VirtualMachine

      protected VirtualMachine(AttachProvider  provider, String  id)
      初始化此类的新实例。
      参数：
      provider - 创建此类的附加提供程序。
      id - 标识 Java 虚拟机的抽象标识符。
      抛出：
      NullPointerException - 如果 provider 或 id 是 null。

  • 方法详情

    • list

      public static List <VirtualMachineDescriptor > list()
      返回 Java 虚拟机列表。

      此方法返回 Java VirtualMachineDescriptor 元素的列表。该列表是通过调用所有已安装 attach providers 的 listVirtualMachines 方法获得的虚拟机描述符列表的集合。如果没有任何提供者已知的 Java 虚拟机，则返回一个空列表。

      返回：
      虚拟机描述符列表。

    • attach

      public static VirtualMachine  attach(String  id) throws AttachNotSupportedException , IOException
      附加到 Java 虚拟机。

      此方法通过调用 AttachProvider.providers() 方法获取附加提供程序列表。然后它遍历列表并依次调用每个提供者的 attachVirtualMachine 方法。如果提供者成功附加，则迭代终止，并且由成功附加的提供者创建的 VirtualMachine 通过此方法返回。如果所有提供者的 attachVirtualMachine 方法抛出 AttachNotSupportedException 那么这个方法也会抛出 AttachNotSupportedException 。这意味着当提供给此方法的标识符无效时，将抛出 AttachNotSupportedException ，或者标识符对应于不存在的 Java 虚拟机，或者没有提供者可以附加到它。如果 AttachProvider.providers() 返回空列表，也会抛出此异常。

      参数：
      id - 标识 Java 虚拟机的抽象标识符。
      返回：
      代表目标 VM 的 VirtualMachine。
      抛出：
      SecurityException - 如果已安装安全管理器并且它拒绝 AttachPermission ("attachVirtualMachine") 或实施所需的其他权限。
      AttachNotSupportedException - 如果所有已安装提供程序的 attachVirtualmachine 方法抛出 AttachNotSupportedException ，或者没有安装任何提供程序。
      IOException - 如果发生 I/O 错误
      NullPointerException - 如果 id 是 null。

    • attach

      public static VirtualMachine  attach(VirtualMachineDescriptor  vmd) throws AttachNotSupportedException , IOException
      附加到 Java 虚拟机。

      此方法首先调用给定虚拟机描述符的provider() 方法来获取附加提供程序。然后调用附加提供程序的 attachVirtualMachine 附加到目标 VM。

      参数：
      vmd - 虚拟机描述符。
      返回：
      代表目标 VM 的 VirtualMachine。
      抛出：
      SecurityException - 如果已安装安全管理器并且它拒绝 AttachPermission ("attachVirtualMachine") 或实施所需的其他权限。
      AttachNotSupportedException - 如果附加提供者的 attachVirtualmachine 抛出 AttachNotSupportedException 。
      IOException - 如果发生 I/O 错误
      NullPointerException - 如果 vmd 是 null。

    • detach

      public abstract void detach() throws IOException
      与虚拟机分离。

      从虚拟机分离后，任何进一步尝试调用该虚拟机上的操作都将导致抛出 IOException 。如果在调用此方法时正在进行操作（例如 loadAgent ），则该行为取决于实现。换句话说，操作完成或抛出 IOException 是特定于实现的。

      如果已经与虚拟机分离，则调用此方法无效。

      抛出：
      IOException - 如果发生 I/O 错误

    • provider

      public final AttachProvider  provider()
      返回创建此虚拟机的提供者。
      返回：
      创建此虚拟机的提供商。

    • id

      public final String  id()
      返回此 Java 虚拟机的标识符。
      返回：
      此 Java 虚拟机的标识符。

    • loadAgentLibrary

      public abstract void loadAgentLibrary(String  agentLibrary, String  options) throws AgentLoadException , AgentInitializationException , IOException
      加载代理库。

      JVM TI 客户端称为代理人.它是用母语开发的。 JVM TI 代理以特定于平台的方式部署，但它通常是动态库的平台等价物。或者，它可以静态链接到 VM。此方法导致将给定的代理库加载到目标 VM 中（如果尚未加载或未静态链接到 VM 中）。然后，它会导致目标 VM 调用 Agent_OnAttach 函数，或者对于名为“L”的静态链接代理，调用 JVM 工具接口 规范中指定的 Agent_OnAttach_L 函数。请注意，即使在调用此方法之前加载了代理库，也会调用 Agent_OnAttach[_L] 函数。

      提供的代理库是代理库的名称。它以依赖于实现的方式在目标虚拟机中进行解释。通常，一个实现会将库名称扩展为操作系统特定的文件名。例如，在 UNIX 系统上，名称 L 可能会扩展为 libL.so，并使用 LD_LIBRARY_PATH 环境变量指定的搜索路径进行定位。如果名为“L”的代理静态链接到 VM，则 VM 必须导出名为 Agent_OnAttach_L 的函数。

      如果代理库中的 Agent_OnAttach[_L] 函数返回错误，则会抛出 AgentInitializationException 。然后可以通过对异常调用 returnValue 方法来获取 Agent_OnAttach[_L] 的返回值。

      参数：
      agentLibrary - 代理库的名称。
      options - 提供给 Agent_OnAttach[_L] 函数的选项（可以是 null ）。
      抛出：
      AgentLoadException - 如果代理库不存在，则代理库未静态链接到 VM，或者由于其他原因无法加载代理库。
      AgentInitializationException - 如果 Agent_OnAttach[_L] 函数返回错误。
      IOException - 如果发生 I/O 错误
      NullPointerException - 如果 agentLibrary 是 null。
      参见：

    • loadAgentLibrary

      public void loadAgentLibrary(String  agentLibrary) throws AgentLoadException , AgentInitializationException , IOException
      加载代理库。

      这个方便的方法就像调用一样：

      loadAgentLibrary(agentLibrary, null);
      参数：
      agentLibrary - 代理库的名称。
      抛出：
      AgentLoadException - 如果代理库不存在，则代理库未静态链接到 VM，或者由于其他原因无法加载代理库。
      AgentInitializationException - 如果 Agent_OnAttach[_L] 函数返回错误。
      IOException - 如果发生 I/O 错误
      NullPointerException - 如果 agentLibrary 是 null。

    • loadAgentPath

      public abstract void loadAgentPath(String  agentPath, String  options) throws AgentLoadException , AgentInitializationException , IOException
      通过完整路径名加载本机代理库。

      JVM TI 客户端称为代理人.它是用母语开发的。 JVM TI 代理以特定于平台的方式部署，但它通常是动态库的平台等价物。或者，由 agentPath 参数指定的本机库可以与 VM 静态链接。将 agentPath 参数解析为静态链接库名称是在 VM 中以特定于平台的方式完成的。例如，在 UNIX 中，/a/b/libL.so 的 agentPath 参数会将库命名为“L”。有关详细信息，请参阅 JVM TI 规范。此方法导致将给定的代理库加载到目标 VM 中（如果尚未加载或未静态链接到 VM 中）。然后，它会导致目标 VM 调用 Agent_OnAttach 函数，或者对于名为“L”的静态链接代理，调用 JVM 工具接口 规范中指定的 Agent_OnAttach_L 函数。请注意，即使在调用此方法之前加载了代理库，也会调用 Agent_OnAttach[_L] 函数。

      提供的代理库是加载代理库的绝对路径。与 loadAgentLibrary 不同，库名称不会在目标虚拟机中扩展。

      如果代理库中的 Agent_OnAttach[_L] 函数返回错误，则会抛出 AgentInitializationException 。然后可以通过对异常调用 returnValue 方法来获取 Agent_OnAttach[_L] 的返回值。

      参数：
      agentPath - 代理库的完整路径。
      options - 提供给 Agent_OnAttach[_L] 函数的选项（可以是 null ）。
      抛出：
      AgentLoadException - 如果代理库不存在，则代理库未静态链接到 VM，或者由于其他原因无法加载代理库。
      AgentInitializationException - 如果 Agent_OnAttach[_L] 函数返回错误。
      IOException - 如果发生 I/O 错误
      NullPointerException - 如果 agentPath 是 null。
      参见：

    • loadAgentPath

      public void loadAgentPath(String  agentPath) throws AgentLoadException , AgentInitializationException , IOException
      通过完整路径名加载本机代理库。

      这个方便的方法就像调用一样：

      loadAgentPath(agentLibrary, null);
      参数：
      agentPath - 代理库的完整路径。
      抛出：
      AgentLoadException - 如果代理库不存在，则代理库未静态链接到 VM，或者由于其他原因无法加载代理库。
      AgentInitializationException - 如果 Agent_OnAttach[_L] 函数返回错误。
      IOException - 如果发生 I/O 错误
      NullPointerException - 如果 agentPath 是 null。

    • loadAgent

      public abstract void loadAgent(String  agent, String  options) throws AgentLoadException , AgentInitializationException , IOException
      加载代理。

      提供给此方法的代理是目标虚拟机文件系统上 JAR 文件的路径名。该路径被传递到解释它的目标虚拟机。目标虚拟机尝试启动 java.lang.instrument 规范指定的代理程序。也就是说，将指定的 JAR 文件添加到（目标虚拟机的）系统类路径，并调用由 JAR 清单中的 Agent-Class 属性指定的代理类的 agentmain 方法。此方法在 agentmain 方法完成时完成。

      参数：
      agent - 包含代理的 JAR 文件的路径。
      options - 提供给代理的 agentmain 方法的选项（可以是 null ）。
      抛出：
      AgentLoadException - 如果代理不存在，或者无法以 java.lang.instrument 规范中指定的方式启动。
      AgentInitializationException - 如果 agentmain 抛出异常
      IOException - 如果发生 I/O 错误
      NullPointerException - 如果 agent 是 null。

    • loadAgent

      public void loadAgent(String  agent) throws AgentLoadException , AgentInitializationException , IOException
      加载代理。

      这个方便的方法就像调用一样：

      loadAgent(agent, null);
      参数：
      agent - 包含代理的 JAR 文件的路径。
      抛出：
      AgentLoadException - 如果代理不存在，或者无法以 java.lang.instrument 规范中指定的方式启动。
      AgentInitializationException - 如果 agentmain 抛出异常
      IOException - 如果发生 I/O 错误
      NullPointerException - 如果 agent 是 null。

    • getSystemProperties

      public abstract Properties  getSystemProperties() throws IOException
      返回目标虚拟机中的当前系统属性。

      此方法返回目标虚拟机中的系统属性。键或值不是 String 的属性将被忽略。该方法大致等同于在目标虚拟机中调用方法 System.getProperties ，只是不包括键或值不是 String 的属性。

      此方法通常用于决定使用 loadAgent 或 loadAgentLibrary 将哪个代理加载到目标虚拟机中。例如，java.home 或 user.dir 属性可能用于创建代理库或 JAR 文件的路径。

      返回：
      系统属性
      抛出：
      AttachOperationFailedException - 如果目标虚拟机无法完成附加操作。 Throwable.getMessage() 将给出更具体的错误消息。
      IOException - 如果发生 I/O 错误，例如通信错误，无法将其识别为指示目标 VM 中操作失败的错误。
      参见：

    • getAgentProperties

      public abstract Properties  getAgentProperties() throws IOException
      返回当前代理属性在目标虚拟机中。

      目标虚拟机可以代表代理维护一个属性列表。完成此操作的方式、属性的名称以及允许的值类型是特定于实现的。代理属性通常用于存储通信端点和其他代理配置详细信息。例如，调试器代理可能会为其传输地址创建一个代理属性。

      此方法返回键和值为 String 的代理属性。键或值不是 String 的属性将被忽略。如果目标虚拟机中没有维护代理属性，则返回一个空属性列表。

      返回：
      代理属性
      抛出：
      AttachOperationFailedException - 如果目标虚拟机无法完成附加操作。 Throwable.getMessage() 将给出更具体的错误消息。
      IOException - 如果发生 I/O 错误，例如通信错误，无法将其识别为指示目标 VM 中操作失败的错误。

    • startManagementAgent

      public abstract void startManagementAgent(Properties  agentProperties) throws IOException
      在目标虚拟机中启动 JMX 管理代理。

      配置属性与启动 JMX 管理代理时在命令行上指定的属性相同。与在命令行上一样，您至少需要指定 com.sun.management.jmxremote.port 属性。

      有关详细信息，请参阅 使用 JMX 技术进行监控和管理 的联机文档。

      参数：
      agentProperties - 包含代理配置属性的 Properties 对象。
      抛出：
      AttachOperationFailedException - 如果目标虚拟机无法完成附加操作。 Throwable.getMessage() 将给出更具体的错误消息。
      IOException - 如果发生 I/O 错误，例如通信错误，无法将其识别为指示目标 VM 中操作失败的错误。
      IllegalArgumentException - 如果 agentProperties 中的键或值无效。
      NullPointerException - 如果 agentProperties 为空。
      自从：
      1.8

    • startLocalManagementAgent

      public abstract String  startLocalManagementAgent() throws IOException
      在目标虚拟机中启动本地 JMX 管理代理。

      有关详细信息，请参阅 使用 JMX 技术进行监控和管理 的联机文档。

      返回：
      本地连接器服务地址的字符串表示形式。该值可以由 JMXServiceURL(String) 构造函数解析。
      抛出：
      AttachOperationFailedException - 如果目标虚拟机无法完成附加操作。 Throwable.getMessage() 将给出更具体的错误消息。
      IOException - 如果发生 I/O 错误，例如通信错误，无法将其识别为指示目标 VM 中操作失败的错误。
      自从：
      1.8

    • hashCode

      public int hashCode()
      返回此 VirtualMachine 的哈希码值。哈希码基于 VirtualMachine 的组件，并满足 Object.hashCode 方法的一般契约。
      重写：
      hashCode 在类 Object 中
      返回：
      此虚拟机的哈希码值
      参见：

    • equals

      public boolean equals(Object  ob)
      测试此 VirtualMachine 是否与另一个对象相等。

      如果给定对象不是 VirtualMachine，则此方法返回 false。两个 VirtualMachines 被认为是相等的要求它们都引用相同的提供者，并且它们的 identifiers 是相等的。

      此方法满足Object.equals 方法的一般契约。

      重写：
      equals 在类 Object 中
      参数：
      ob - 此对象要与之比较的对象
      返回：
      true 当且仅当给定对象是等于此 VirtualMachine 的 VirtualMachine。
      参见：

    • toString

      public String  toString()
      返回 VirtualMachine 的字符串表示形式。
      重写：
      toString 在类 Object 中
      返回：
      对象的字符串表示形式。