Module jdk.attach
Package com.sun.tools.attach

Class VirtualMachine

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

VirtualMachine表示一个Java虚拟机，该Java虚拟机已连接到。它连接的Java虚拟机有时被称为目标虚拟机或目标VM。一个应用程序（通常是诸如管理控制台或分析器之类的工具）使用VirtualMachine将代理加载到目标VM中。例如，用Java语言编写的分析器工具可能会附加到运行中的应用程序，并加载其分析器代理以对运行中的应用程序进行分析。

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

除了加载代理，VirtualMachine还提供对目标VM中的系统属性的读取访问。在某些环境中，这可能很有用，例如使用诸如java.home、os.name或os.arch之类的属性构造将加载到目标VM中的代理的路径。

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

      // 附加到目标VM
      VirtualMachine vm = VirtualMachine.attach("2177");

      // 启动管理代理
      Properties props = new Properties();
      props.put("com.sun.management.jmxremote.port", "5000");
      vm.startManagementAgent(props);

      // 分离
      vm.detach();

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

VirtualMachine可安全用于多个并发线程。

自版本:
1.6

  • Constructor Details

    • VirtualMachine

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

  • Method Details

    • list

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

      此方法返回Java VirtualMachineDescriptor元素的列表。该列表是通过调用所有已安装的listVirtualMachines方法获取的虚拟机描述符列表的聚合。如果没有任何提供程序知道任何Java虚拟机，则返回空列表。

      返回:
      虚拟机描述符的列表。

    • attach

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

      此方法通过调用AttachProvider.providers()方法获取附加提供程序的列表。然后遍历列表，并依次调用每个提供程序的attachVirtualMachine方法。如果提供程序成功附加，则迭代终止，并由成功附加的提供程序创建的VirtualMachine由此方法返回。如果所有提供程序的attachVirtualMachine方法都抛出AttachNotSupportedException，则此方法也会抛出AttachNotSupportedException。这意味着当提供给此方法的标识符无效，或标识符对应于不存在的Java虚拟机，或没有提供程序能够附加到它时，将抛出AttachNotSupportedException。如果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调用JVM工具接口规范中指定的Agent_OnAttach函数或对于名为'L'的静态链接代理，调用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静态链接。在VM中，将agentPath参数解析为静态链接库名称是以特定于平台的方式完成的。例如，在UNIX中，/a/b/libL.so的agentPath参数将命名一个库'L'。有关更多详细信息，请参阅JVM TI规范。此方法导致给定的代理库加载到目标VM中（如果尚未加载或未静态链接到VM中）。然后，它导致目标VM调用JVM工具接口规范中指定的Agent_OnAttach函数或对于名为'L'的静态链接代理，调用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的属性。

      此方法通常用于决定要加载到目标虚拟机中的代理。例如，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为null。
      自:
      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。要考虑两个VirtualMachine相等，需要它们都引用相同的提供程序，并且它们的标识符相等。

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

      覆盖:
      equals 在类 Object中
      参数:
      ob - 要将此对象与之比较的对象
      返回:
      如果给定对象是等于此VirtualMachine的VirtualMachine，则返回true。
      参见:

    • toString

      public String toString()
      返回VirtualMachine的字符串表示形式。
      覆盖:
      toString 在类 Object中
      返回:
      对象的字符串表示形式。