public abstract class VirtualMachine
extends java.lang.Object
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, a VirtualMachine
instance is obtained by invoking the
attach
method with a VirtualMachineDescriptor
obtained
from the list of virtual machine descriptors returned by the list
method.
Once a reference to a virtual machine is obtained, the loadAgent
,
loadAgentLibrary
, and loadAgentPath
methods are used to load agents into target virtual machine. The loadAgent
method is used to load agents that are written in the Java
Language and deployed in a JAR file
. (See
java.lang.instrument
for a detailed description on how these agents
are loaded and started). The loadAgentLibrary
and
loadAgentPath
methods are used to load agents that
are deployed either in a dynamic library or statically linked into the VM 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 as
java.home
, os.name
, or os.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.
Modifier | Constructor and Description |
---|---|
protected |
VirtualMachine(AttachProvider provider,
java.lang.String id)
Initializes a new instance of this class.
|
Modifier and Type | Method and Description |
---|---|
static VirtualMachine |
attach(java.lang.String id)
Attaches to a Java virtual machine.
|
static VirtualMachine |
attach(VirtualMachineDescriptor vmd)
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 the
VirtualMachine . |
protected VirtualMachine(AttachProvider provider, java.lang.String id)
provider
- The attach provider creating this class.id
- The abstract identifier that identifies the Java virtual machine.java.lang.NullPointerException
- If provider
or id
is null
.public static java.util.List<VirtualMachineDescriptor> list()
This method returns a list of Java com.sun.tools.attach.VirtualMachineDescriptor
elements.
The list is an aggregation of the virtual machine
descriptor lists obtained by invoking the listVirtualMachines
method of all installed
attach providers
.
If there are no Java virtual machines known to any provider
then an empty list is returned.
public static VirtualMachine attach(java.lang.String id) throws AttachNotSupportedException, java.io.IOException
This method obtains the list of attach providers by invoking the
AttachProvider.providers()
method. It then iterates overs the list
and invokes each provider's attachVirtualMachine
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 the attachVirtualMachine
method of all providers throws
AttachNotSupportedException
then this method also throws AttachNotSupportedException
.
This means that AttachNotSupportedException
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 if
AttachProvider.providers()
returns an empty list.
id
- The abstract identifier that identifies the Java virtual machine.java.lang.SecurityException
- If a security manager has been installed and it denies
AttachPermission
("attachVirtualMachine"), or another permission
required by the implementation.AttachNotSupportedException
- If the attachVirtualmachine
method of all installed
providers throws AttachNotSupportedException
, or
there aren't any providers installed.java.io.IOException
- If an I/O error occursjava.lang.NullPointerException
- If id
is null
.public static VirtualMachine attach(VirtualMachineDescriptor vmd) throws AttachNotSupportedException, java.io.IOException
This method first invokes the provider()
method
of the given virtual machine descriptor to obtain the attach provider. It
then invokes the attach provider's attachVirtualMachine
to attach to the target VM.
vmd
- The virtual machine descriptor.java.lang.SecurityException
- If a security manager has been installed and it denies
AttachPermission
("attachVirtualMachine"), or another permission
required by the implementation.AttachNotSupportedException
- If the attach provider's attachVirtualmachine
throws AttachNotSupportedException
.java.io.IOException
- If an I/O error occursjava.lang.NullPointerException
- If vmd
is null
.public abstract void detach() throws java.io.IOException
After detaching from the virtual machine, any further attempt to invoke
operations on that virtual machine will cause an IOException
to be thrown. If an operation (such as loadAgent
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.
java.io.IOException
- If an I/O error occurspublic final AttachProvider provider()
public final java.lang.String id()
public abstract void loadAgentLibrary(java.lang.String agentLibrary, java.lang.String options) throws AgentLoadException, AgentInitializationException, java.io.IOException
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. Alternatively, it may be statically linked into the VM.
This method causes the given agent library to be loaded into the target
VM (if not already loaded or if not statically linked into the VM).
It then causes the target VM to invoke the Agent_OnAttach
function
or, for a statically linked agent named 'L', the Agent_OnAttach_L
function
as specified in the
JVM Tools
Interface specification. Note that the Agent_OnAttach[_L]
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 L might be expanded to
libL.so, and located using the search path specified by the
LD_LIBRARY_PATH environment variable. If the agent named 'L' is
statically linked into the VM then the VM must export a function named
Agent_OnAttach_L
.
If the Agent_OnAttach[_L]
function in the agent library returns
an error then an com.sun.tools.attach.AgentInitializationException
is
thrown. The return value from the Agent_OnAttach[_L]
can then be
obtained by invoking the returnValue
method on the exception.
agentLibrary
- The name of the agent library.options
- The options to provide to the Agent_OnAttach[_L]
function (can be null
).AgentLoadException
- If the agent library does not exist, the agent library is not
statically linked with the VM, or the agent library cannot be
loaded for another reason.AgentInitializationException
- If the Agent_OnAttach[_L]
function returns an error.java.io.IOException
- If an I/O error occursjava.lang.NullPointerException
- If agentLibrary
is null
.com.sun.tools.attach.AgentInitializationException#returnValue()
public void loadAgentLibrary(java.lang.String agentLibrary) throws AgentLoadException, AgentInitializationException, java.io.IOException
This convenience method works as if by invoking:
loadAgentLibrary
(agentLibrary, null);
agentLibrary
- The name of the agent library.AgentLoadException
- If the agent library does not exist, the agent library is not
statically linked with the VM, or the agent library cannot be
loaded for another reason.AgentInitializationException
- If the Agent_OnAttach[_L]
function returns an error.java.io.IOException
- If an I/O error occursjava.lang.NullPointerException
- If agentLibrary
is null
.public abstract void loadAgentPath(java.lang.String agentPath, java.lang.String options) throws AgentLoadException, AgentInitializationException, java.io.IOException
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. Alternatively, the native
library specified by the agentPath parameter may be statically
linked with the VM. The parsing of the agentPath parameter into
a statically linked library name is done in a platform
specific manner in the VM. For example, in UNIX, an agentPath parameter
of /a/b/libL.so
would name a library 'L'.
See the JVM TI Specification for more details.
This method causes the given agent library to be loaded into the target
VM (if not already loaded or if not statically linked into the VM).
It then causes the target VM to invoke the Agent_OnAttach
function or, for a statically linked agent named 'L', the
Agent_OnAttach_L
function as specified in the
JVM Tools
Interface specification.
Note that the Agent_OnAttach[_L]
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. Unlike loadAgentLibrary
, the library name
is not expanded in the target virtual machine.
If the Agent_OnAttach[_L]
function in the agent library returns
an error then an com.sun.tools.attach.AgentInitializationException
is
thrown. The return value from the Agent_OnAttach[_L]
can then be
obtained by invoking the returnValue
method on the exception.
agentPath
- The full path of the agent library.options
- The options to provide to the Agent_OnAttach[_L]
function (can be null
).AgentLoadException
- If the agent library does not exist, the agent library is not
statically linked with the VM, or the agent library cannot be
loaded for another reason.AgentInitializationException
- If the Agent_OnAttach[_L]
function returns an error.java.io.IOException
- If an I/O error occursjava.lang.NullPointerException
- If agentPath
is null
.com.sun.tools.attach.AgentInitializationException#returnValue()
public void loadAgentPath(java.lang.String agentPath) throws AgentLoadException, AgentInitializationException, java.io.IOException
This convenience method works as if by invoking:
loadAgentPath
(agentLibrary, null);
agentPath
- The full path to the agent library.AgentLoadException
- If the agent library does not exist, the agent library is not
statically linked with the VM, or the agent library cannot be
loaded for another reason.AgentInitializationException
- If the Agent_OnAttach[_L]
function returns an error.java.io.IOException
- If an I/O error occursjava.lang.NullPointerException
- If agentPath
is null
.public abstract void loadAgent(java.lang.String agent, java.lang.String options) throws AgentLoadException, AgentInitializationException, java.io.IOException
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 the agentmain
method of the agent class, specified
by the Agent-Class
attribute in the JAR manifest, is invoked. This
method completes when the agentmain
method completes.
agent
- Path to the JAR file containing the agent.options
- The options to provide to the agent's agentmain
method (can be null
).AgentLoadException
- If the agent does not exist, or cannot be started in the manner
specified in the java.lang.instrument
specification.AgentInitializationException
- If the agentmain
throws an exceptionjava.io.IOException
- If an I/O error occursjava.lang.NullPointerException
- If agent
is null
.public void loadAgent(java.lang.String agent) throws AgentLoadException, AgentInitializationException, java.io.IOException
This convenience method works as if by invoking:
loadAgent
(agent, null);
agent
- Path to the JAR file containing the agent.AgentLoadException
- If the agent does not exist, or cannot be started in the manner
specified in the java.lang.instrument
specification.AgentInitializationException
- If the agentmain
throws an exceptionjava.io.IOException
- If an I/O error occursjava.lang.NullPointerException
- If agent
is null
.public abstract java.util.Properties getSystemProperties() throws java.io.IOException
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
method System.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 with loadAgent
, or
loadAgentLibrary
. For example, the
java.home
or user.dir
properties might be
use to create the path to the agent library or JAR file.
java.io.IOException
- If an I/O error occursSystem.getProperties()
,
loadAgentLibrary(java.lang.String, java.lang.String)
,
loadAgent(java.lang.String, java.lang.String)
public abstract java.util.Properties getAgentProperties() throws java.io.IOException
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.
java.io.IOException
- If an I/O error occurspublic int hashCode()
Object.hashCode
method.hashCode
in class java.lang.Object
public boolean equals(java.lang.Object ob)
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 Object.equals
method.
equals
in class java.lang.Object
ob
- The object to which this object is to be comparedpublic java.lang.String toString()
VirtualMachine
.toString
in class java.lang.Object