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

Class VirtualMachine

  • public abstract class VirtualMachineextends Object
    一个Java虚拟机。

    VirtualMachine表示此Java虚拟机已附加到的Java虚拟机。 它所连接的Java虚拟机有时称为目标虚拟机或目标VM 。 应用程序（通常是诸如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 。 这意味着当提供给此方法的标识符无效或者标识符对应于不存在的Java虚拟机或者没有任何提供程序可以附加到该方法时，将抛出AttachNotSupportedException 。 如果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
        加载代理库。

        JVM TI客户端称为代理 。 它是用母语开发的。 JVM TI代理以特定于平台的方式部署，但它通常是与动态库等效的平台。 或者，它可以静态链接到VM。 此方法会将给定的代理程序库加载到目标VM中（如果尚未加载或未静态链接到VM中）。 然后，它使目标VM调用Agent_OnAttach函数，或者对于名为“L”的静态链接代理，调用JVM Tools Interface规范中指定的Agent_OnAttach_L函数。 请注意，即使在调用此方法之前加载了代理库，也会调用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
        按完整路径名加载本机代理库。

        JVM TI客户端称为代理 。 它是用母语开发的。 JVM TI代理以特定于平台的方式部署，但它通常是与动态库等效的平台。 或者，agentPath参数指定的本机库可以与VM静态链接。 将agentPath参数解析为静态链接的库名称是在VM中以特定于平台的方式完成的。 例如，在UNIX中，agentPath参数/a/b/libL.so将命名库“L”。 有关更多详细信息，请参阅JVM TI规范。 此方法会将给定的代理程序库加载到目标VM中（如果尚未加载或未静态链接到VM中）。 然后，它使目标VM调用Agent_OnAttach函数，或者对于名为“L”的静态链接代理，调用JVM Tools Interface规范中指定的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
        结果
        对象的字符串表示形式。