- java.lang.Object
-
- com.sun.tools.attach.VirtualMachine
-
public abstract class VirtualMachine extends 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
-
-
构造方法摘要
构造方法 变量 构造器 描述 protected
VirtualMachine(AttachProvider provider, String id)
初始化此类的新实例。
-
方法摘要
所有方法 静态方法 实例方法 抽象方法 具体的方法 变量和类型 方法 描述 static VirtualMachine
attach(VirtualMachineDescriptor vmd)
附加到Java虚拟机。static VirtualMachine
attach(String id)
附加到Java虚拟机。abstract void
detach()
从虚拟机中分离。boolean
equals(Object ob)
测试此VirtualMachine是否与另一个对象相等。abstract Properties
getAgentProperties()
返回目标虚拟机中的当前 代理属性 。abstract Properties
getSystemProperties()
返回目标虚拟机中的当前系统属性。int
hashCode()
返回此VirtualMachine的哈希码值。String
id()
返回此Java虚拟机的标识符。static List<VirtualMachineDescriptor>
list()
返回Java虚拟机列表。void
loadAgent(String agent)
加载代理。abstract void
loadAgent(String agent, String options)
加载代理。void
loadAgentLibrary(String agentLibrary)
加载代理库。abstract void
loadAgentLibrary(String agentLibrary, String options)
加载代理库。void
loadAgentPath(String agentPath)
按完整路径名加载本机代理库。abstract void
loadAgentPath(String agentPath, String options)
按完整路径名加载本机代理库。AttachProvider
provider()
返回创建此虚拟机的提供程序。abstract String
startLocalManagementAgent()
在目标虚拟机中启动本地JMX管理代理程序。abstract void
startManagementAgent(Properties agentProperties)
在目标虚拟机中启动JMX管理代理程序。String
toString()
返回VirtualMachine
的字符串表示VirtualMachine
。
-
-
-
构造方法详细信息
-
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
。 这意味着当提供给此方法的标识符无效或者标识符对应于不存在的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调用
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()
-
loadAgentLibrary
public void loadAgentLibrary(String agentLibrary) throws AgentLoadException, AgentInitializationException, IOException
- 参数
-
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中,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()
-
loadAgentPath
public void loadAgentPath(String agentPath) throws AgentLoadException, AgentInitializationException, IOException
- 参数
-
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
方法完成时,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
- 参数
-
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中的操作失败。 - 另请参见:
-
System.getProperties()
,loadAgentLibrary(java.lang.String, java.lang.String)
,loadAgent(java.lang.String, java.lang.String)
-
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
-
startLocalManagementAgent
public abstract String startLocalManagementAgent() throws IOException
在目标虚拟机中启动本地JMX管理代理程序。有关更多详细信息,请参阅Monitoring and Management Using JMX Technology的在线文档。
- 结果
-
本地连接器的服务地址的String表示形式。
该值可以由
JMXServiceURL(String)
构造函数解析。 - 异常
-
AttachOperationFailedException
- 如果目标虚拟机无法完成附加操作。Throwable.getMessage()
将给出更具体的错误消息。 -
IOException
- 如果发生I / O错误,则会出现通信错误,该错误无法识别为错误以指示目标VM中的操作失败。 - 从以下版本开始:
- 1.8
-
hashCode
public int hashCode()
返回此VirtualMachine的哈希码值。 哈希码基于VirtualMachine的组件,并满足Object.hashCode
方法的常规协定。- 重写:
-
hashCode
在类Object
- 结果
- 此虚拟机的哈希码值
- 另请参见:
-
Object.equals(java.lang.Object)
,System.identityHashCode(java.lang.Object)
-
equals
public boolean equals(Object ob)
测试此VirtualMachine是否与另一个对象相等。如果给定对象不是VirtualMachine,则此方法返回
false
。 要使两个VirtualMachines被认为是相同的,要求它们都引用相同的提供程序,并且它们的identifiers
是相同的。该方法满足
Object.equals
方法的一般合同。- 重写:
-
equals
在类Object
- 参数
-
ob
- 要与此对象进行比较的对象 - 结果
-
true
当且仅当给定对象是等于此VirtualMachine的VirtualMachine时。 - 另请参见:
-
Object.hashCode()
,HashMap
-
-