Class VirtualMachine
- java.lang.Object
-
- com.sun.tools.attach.VirtualMachine
-
- Direct Known Subclasses:
HotSpotVirtualMachine
public abstract class VirtualMachine extends java.lang.Object
A Java virtual machine.
A
VirtualMachine
represents a Java virtual machine to which this Java virtual machine has attached. The Java virtual machine to which it is attached is sometimes called the target virtual machine, or target VM. An application (typically a tool such as a managemet console or profiler) uses a VirtualMachine to load an agent into the target VM. For example, a profiler tool written in the Java Language might attach to a running application and load its profiler agent to profile the running application.A VirtualMachine is obtained by invoking the
attach
method with an identifier that identifies the target virtual machine. The identifier is implementation-dependent but is typically the process identifier (or pid) in environments where each Java virtual machine runs in its own operating system process. Alternatively, aVirtualMachine
instance is obtained by invoking theattach
method with aVirtualMachineDescriptor
obtained from the list of virtual machine descriptors returned by thelist
method. Once a reference to a virtual machine is obtained, theloadAgent
,loadAgentLibrary
, andloadAgentPath
methods are used to load agents into target virtual machine. TheloadAgent
method is used to load agents that are written in the Java Language and deployed in aJAR file
. (Seejava.lang.instrument
for a detailed description on how these agents are loaded and started). TheloadAgentLibrary
andloadAgentPath
methods are used to load agents that are deployed in a dynamic library and make use of the JVM Tools Interface.In addition to loading agents a VirtualMachine provides read access to the
system properties
in the target VM. This can be useful in some environments where properties such asjava.home
,os.name
, oros.arch
are used to construct the path to agent that will be loaded into the target VM.The following example demonstrates how VirtualMachine may be used:
// attach to target VM VirtualMachine vm = VirtualMachine.attach("2177"); // get system properties in target VM Properties props = vm.getSystemProperties(); // construct path to management agent String home = props.getProperty("java.home"); String agent = home + File.separator + "lib" + File.separator + "management-agent.jar"; // load agent into target VM vm.loadAgent(agent, "com.sun.management.jmxremote.port=5000"); // detach vm.detach();
In this example we attach to a Java virtual machine that is identified by the process identifier
2177
. The system properties from the target VM are then used to construct the path to a management agent which is then loaded into the target VM. Once loaded the client detaches from the target VM.A VirtualMachine is safe for use by multiple concurrent threads.
- Since:
- 1.6
-
-
Field Summary
Fields Modifier and Type Field Description private int
hash
private java.lang.String
id
private AttachProvider
provider
-
Constructor Summary
Constructors Modifier Constructor Description protected
VirtualMachine(AttachProvider provider, java.lang.String id)
Initializes a new instance of this class.
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description static VirtualMachine
attach(VirtualMachineDescriptor vmd)
Attaches to a Java virtual machine.static VirtualMachine
attach(java.lang.String id)
Attaches to a Java virtual machine.abstract void
detach()
Detach from the virtual machine.boolean
equals(java.lang.Object ob)
Tests this VirtualMachine for equality with another object.abstract java.util.Properties
getAgentProperties()
Returns the current agent properties in the target virtual machine.abstract java.util.Properties
getSystemProperties()
Returns the current system properties in the target virtual machine.int
hashCode()
Returns a hash-code value for this VirtualMachine.java.lang.String
id()
Returns the identifier for this Java virtual machine.static java.util.List<VirtualMachineDescriptor>
list()
Return a list of Java virtual machines.void
loadAgent(java.lang.String agent)
Loads an agent.abstract void
loadAgent(java.lang.String agent, java.lang.String options)
Loads an agent.void
loadAgentLibrary(java.lang.String agentLibrary)
Loads an agent library.abstract void
loadAgentLibrary(java.lang.String agentLibrary, java.lang.String options)
Loads an agent library.void
loadAgentPath(java.lang.String agentPath)
Load a native agent library by full pathname.abstract void
loadAgentPath(java.lang.String agentPath, java.lang.String options)
Load a native agent library by full pathname.AttachProvider
provider()
Returns the provider that created this virtual machine.java.lang.String
toString()
Returns the string representation of theVirtualMachine
.
-
-
-
Field Detail
-
provider
private final AttachProvider provider
-
id
private final java.lang.String id
-
hash
private volatile int hash
-
-
Constructor Detail
-
VirtualMachine
protected VirtualMachine(AttachProvider provider, java.lang.String id)
Initializes a new instance of this class.- Parameters:
provider
- The attach provider creating this class.id
- The abstract identifier that identifies the Java virtual machine.
-
-
Method Detail
-
list
public static java.util.List<VirtualMachineDescriptor> list()
Return a list of Java virtual machines.
This method returns a list of Java
VirtualMachineDescriptor
elements. The list is an aggregation of the virtual machine descriptor lists obtained by invoking thelistVirtualMachines
method of all installedattach providers
. If there are no Java virtual machines known to any provider then an empty list is returned.- Returns:
- The list of virtual machine descriptors.
-
attach
public static VirtualMachine attach(java.lang.String id) throws AttachNotSupportedException, java.io.IOException
Attaches to a Java virtual machine.
This method obtains the list of attach providers by invoking the
AttachProvider.providers()
method. It then iterates overs the list and invokes each provider'sattachVirtualMachine
method in turn. If a provider successfully attaches then the iteration terminates, and the VirtualMachine created by the provider that successfully attached is returned by this method. If theattachVirtualMachine
method of all providers throwsAttachNotSupportedException
then this method also throwsAttachNotSupportedException
. This means thatAttachNotSupportedException
is thrown when the identifier provided to this method is invalid, or the identifier corresponds to a Java virtual machine that does not exist, or none of the providers can attach to it. This exception is also thrown ifAttachProvider.providers()
returns an empty list.- Parameters:
id
- The abstract identifier that identifies the Java virtual machine.- Returns:
- A VirtualMachine representing the target VM.
- Throws:
java.lang.SecurityException
- If a security manager has been installed and it deniesAttachPermission
("attachVirtualMachine"), or another permission required by the implementation.java.io.IOException
- If an I/O error occursAttachNotSupportedException
-
attach
public static VirtualMachine attach(VirtualMachineDescriptor vmd) throws AttachNotSupportedException, java.io.IOException
Attaches to a Java virtual machine. This method first invokes theprovider()
method of the given virtual machine descriptor to obtain the attach provider. It then invokes the attach provider'sattachVirtualMachine
to attach to the target VM.- Parameters:
vmd
- The virtual machine descriptor.- Returns:
- A VirtualMachine representing the target VM.
- Throws:
java.lang.SecurityException
- If a security manager has been installed and it deniesAttachPermission
("attachVirtualMachine"), or another permission required by the implementation.AttachNotSupportedException
- If the attach provider'sattachVirtualmachine
throwsAttachNotSupportedException
.java.io.IOException
- If an I/O error occursjava.lang.NullPointerException
- Ifvmd
isnull
.
-
detach
public abstract void detach() throws java.io.IOException
Detach from the virtual machine. After detaching from the virtual machine, any further attempt to invoke operations on that virtual machine will cause anIOException
to be thrown. If an operation (such asloadAgent
for example) is in progress when this method is invoked then the behaviour is implementation dependent. In other words, it is implementation specific if the operation completes or throws IOException. If already detached from the virtual machine then invoking this method has no effect.- Throws:
java.io.IOException
- If an I/O error occurs
-
provider
public final AttachProvider provider()
Returns the provider that created this virtual machine.
-
id
public final java.lang.String id()
Returns the identifier for this Java virtual machine.
-
loadAgentLibrary
public abstract void loadAgentLibrary(java.lang.String agentLibrary, java.lang.String options) throws AgentLoadException, AgentInitializationException, java.io.IOException
Loads an agent library. A JVM TI client is called an agent. It is developed in a native language. A JVM TI agent is deployed in a platform specific manner but it is typically the platform equivalent of a dynamic library. This method causes the given agent library to be loaded into the target VM (if not already loaded). It then causes the target VM to invoke theAgent_OnAttach
function as specified in the JVM Tools Interface specification. Note that theAgent_OnAttach
function is invoked even if the agent library was loaded prior to invoking this method. The agent library provided is the name of the agent library. It is interpreted in the target virtual machine in an implementation-dependent manner. Typically an implementation will expand the library name into an operating system specific file name. For example, on UNIX systems, the name foo might be expanded to libfoo.so, and located using the search path specified by the LD_LIBRARY_PATH environment variable. If theAgent_OnAttach
function in the agent library returns an error then anAgentInitializationException
is thrown. The return value from theAgent_OnAttach
can then be obtained by invoking thereturnValue
method on the exception.- Parameters:
agentLibrary
- The name of the agent library.options
- The options to provide to theAgent_OnAttach
function (can benull
).- Throws:
AgentLoadException
- If the agent library does not exist, or cannot be loaded for another reason.AgentInitializationException
- If theAgent_OnAttach
function returns an errorjava.io.IOException
- If an I/O error occursjava.lang.NullPointerException
- IfagentLibrary
isnull
.- See Also:
AgentInitializationException.returnValue()
-
loadAgentLibrary
public void loadAgentLibrary(java.lang.String agentLibrary) throws AgentLoadException, AgentInitializationException, java.io.IOException
Loads an agent library. This convenience method works as if by invoking:loadAgentLibrary
(agentLibrary, null);- Parameters:
agentLibrary
- The name of the agent library.- Throws:
AgentLoadException
- If the agent library does not exist, or cannot be loaded for another reason.AgentInitializationException
- If theAgent_OnAttach
function returns an errorjava.io.IOException
- If an I/O error occursjava.lang.NullPointerException
- IfagentLibrary
isnull
.
-
loadAgentPath
public abstract void loadAgentPath(java.lang.String agentPath, java.lang.String options) throws AgentLoadException, AgentInitializationException, java.io.IOException
Load a native agent library by full pathname. A JVM TI client is called an agent. It is developed in a native language. A JVM TI agent is deployed in a platform specific manner but it is typically the platform equivalent of a dynamic library. This method causes the given agent library to be loaded into the target VM (if not already loaded). It then causes the target VM to invoke theAgent_OnAttach
function as specified in the JVM Tools Interface specification. Note that theAgent_OnAttach
function is invoked even if the agent library was loaded prior to invoking this method. The agent library provided is the absolute path from which to load the agent library. UnlikeloadAgentLibrary
, the library name is not expanded in the target virtual machine. If theAgent_OnAttach
function in the agent library returns an error then anAgentInitializationException
is thrown. The return value from theAgent_OnAttach
can then be obtained by invoking thereturnValue
method on the exception.- Parameters:
agentPath
- The full path of the agent library.options
- The options to provide to theAgent_OnAttach
function (can benull
).- Throws:
AgentLoadException
- If the agent library does not exist, or cannot be loaded for another reason.AgentInitializationException
- If theAgent_OnAttach
function returns an errorjava.io.IOException
- If an I/O error occursjava.lang.NullPointerException
- IfagentPath
isnull
.- See Also:
AgentInitializationException.returnValue()
-
loadAgentPath
public void loadAgentPath(java.lang.String agentPath) throws AgentLoadException, AgentInitializationException, java.io.IOException
Load a native agent library by full pathname. This convenience method works as if by invoking:loadAgentPath
(agentLibrary, null);- Parameters:
agentPath
- The full path to the agent library.- Throws:
AgentLoadException
- If the agent library does not exist, or cannot be loaded for another reason.AgentInitializationException
- If theAgent_OnAttach
function returns an errorjava.io.IOException
- If an I/O error occursjava.lang.NullPointerException
- IfagentPath
isnull
.
-
loadAgent
public abstract void loadAgent(java.lang.String agent, java.lang.String options) throws AgentLoadException, AgentInitializationException, java.io.IOException
Loads an agent.The agent provided to this method is a path name to a JAR file on the file system of the target virtual machine. This path is passed to the target virtual machine where it is interpreted. The target virtual machine attempts to start the agent as specified by the
java.lang.instrument
specification. That is, the specified JAR file is added to the system class path (of the target virtual machine), and theagentmain
method of the agent class, specified by theAgent-Class
attribute in the JAR manifest, is invoked. This method completes when theagentmain
method completes.- Parameters:
agent
- Path to the JAR file containing the agent.options
- The options to provide to the agent'sagentmain
method (can benull
).- Throws:
AgentLoadException
- If the agent does not exist, or cannot be started in the manner specified in thejava.lang.instrument
specification.AgentInitializationException
- If theagentmain
throws an exceptionjava.io.IOException
- If an I/O error occursjava.lang.NullPointerException
- Ifagent
isnull
.
-
loadAgent
public void loadAgent(java.lang.String agent) throws AgentLoadException, AgentInitializationException, java.io.IOException
Loads an agent. This convenience method works as if by invoking:loadAgent
(agent, null);- Parameters:
agent
- Path to the JAR file containing the agent.- Throws:
AgentLoadException
- If the agent does not exist, or cannot be started in the manner specified in thejava.lang.instrument
specification.AgentInitializationException
- If theagentmain
throws an exceptionjava.io.IOException
- If an I/O error occursjava.lang.NullPointerException
- Ifagent
isnull
.
-
getSystemProperties
public abstract java.util.Properties getSystemProperties() throws java.io.IOException
Returns the current system properties in the target virtual machine. This method returns the system properties in the target virtual machine. Properties whose key or value is not a String are omitted. The method is approximately equivalent to the invocation of the methodSystem.getProperties
in the target virtual machine except that properties with a key or value that is not a String are not included. This method is typically used to decide which agent to load into the target virtual machine withloadAgent
, orloadAgentLibrary
. For example, thejava.home
oruser.dir
properties might be use to create the path to the agent library or JAR file.- Returns:
- The system properties
- Throws:
java.io.IOException
- If an I/O error occurs- See Also:
System.getProperties()
,loadAgentLibrary(java.lang.String, java.lang.String)
,loadAgent(java.lang.String, java.lang.String)
-
getAgentProperties
public abstract java.util.Properties getAgentProperties() throws java.io.IOException
Returns the current agent properties in the target virtual machine. The target virtual machine can maintain a list of properties on behalf of agents. The manner in which this is done, the names of the properties, and the types of values that are allowed, is implementation specific. Agent properties are typically used to store communication end-points and other agent configuration details. For example, a debugger agent might create an agent property for its transport address. This method returns the agent properties whose key and value is a String. Properties whose key or value is not a String are omitted. If there are no agent properties maintained in the target virtual machine then an empty property list is returned.- Returns:
- The agent properties
- Throws:
java.io.IOException
- If an I/O error occurs
-
hashCode
public int hashCode()
Returns a hash-code value for this VirtualMachine. The hash code is based upon the VirtualMachine's components, and satisfies the general contract of the Object.hashCode method.- Overrides:
hashCode
in classjava.lang.Object
- Returns:
- A hash-code value for this virtual machine
-
equals
public boolean equals(java.lang.Object ob)
Tests this VirtualMachine for equality with another object.If the given object is not a VirtualMachine then this method returns false. For two VirtualMachines to be considered equal requires that they both reference the same provider, and their
identifiers
are equal.This method satisfies the general contract of the method.
- Overrides:
equals
in classjava.lang.Object
- Parameters:
ob
- The object to which this object is to be compared- Returns:
- true if, and only if, the given object is a VirtualMachine that is equal to this VirtualMachine.
-
toString
public java.lang.String toString()
Returns the string representation of theVirtualMachine
.- Overrides:
toString
in classjava.lang.Object
-
-