Module  jdk.attach
软件包  com.sun.tools.attach

Class VirtualMachine


  • public abstract class VirtualMachine
extends Object
    Java虚拟机。

    A VirtualMachine表示此Java虚拟机已附加到的Java虚拟机。 它所连接的Java虚拟机有时称为目标虚拟机或目标虚拟机 。 应用程序（通常是一个诸如managemet控制台或分析器之类的工具）使用VirtualMachine将代理加载到目标VM中。 例如，用Java语言编写的概要分析工具可能会附加到正在运行的应用程序，并加载其分析器代理程序来配置正在运行的应用程序。

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

    除了加载代理之外，VirtualMachine还提供对目标VM中的system properties的读取访问。 这可以在如属性一些环境中是有用的java.home ， os.name ，或os.arch被用于构建将被装载到目标虚拟机的路径剂。

    以下示例演示如何使用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 。

    • 方法详细信息

      • 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 。

      • 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
        加载代理库。

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

        提供的代理库是代理程序库的名称。 它在目标虚拟机中以实现相关的方式进行解释。 通常，实现将库名称扩展为操作系统特定的文件名。 例如，在UNIX系统上，可以将名称L扩展为libL.so ，并使用由LD_LIBRARY_PATH环境变量指定的搜索路径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 。
        另请参见：
        AgentInitializationException.returnValue()

      • loadAgentPath

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

        A JVM TI客户端称为代理 。 它是用母语开发的。 JVM TI代理以平台特定的方式部署，但通常是与动态库相当的平台。 或者，由agentPath参数指定的本地库可能与VM静态链接。 将agentPath参数解析为静态链接库名称是以平台特定的方式在VM中完成的。 例如，在UNIX中，agentPath参数为/a/b/libL.so将命名库“L”。 有关更多详细信息，请参阅JVM TI规范。 此方法将使给定的代理库加载到目标VM（如果尚未加载或未静态链接到VM中）。 然后，它使目标VM调用Agent_OnAttach函数，或者对于名为“L”的静态链接代理， 270456492219728规范中指定的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 。
        另请参见：
        AgentInitializationException.returnValue()

      • loadAgent

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

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

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

      • 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属性。

        有关详细信息，请参阅Monitoring and Management Using JMX Technology的在线文档。

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

      • equals

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

        如果给定的对象不是VirtualMachine，那么此方法返回false 。 对于两个被认为是相等的VirtualMachines要求他们都引用同一个提供者，而他们的identifiers是相等的。

        该方法满足Object.equals方法的一般合同。

        重写：
        equals在 Object
        参数
        ob - 要比较此对象的对象
        结果
        true如果，并且仅当给定的对象是等于该VirtualMachine的VirtualMachine。
        另请参见：
        Object.hashCode() ， HashMap

      • toString

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