Top Description Fields Constructors Methods
com.sun.tools.attach

public abstract Class VirtualMachine

extends Object
Class Inheritance
Known Direct Subclasses
sun.tools.attach.HotSpotVirtualMachine
Imports
com.sun.tools.attach.spi.AttachProvider, java.util.ArrayList, .List, .Properties, java.io.IOException
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, 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");

     // start management agent
     Properties props = new Properties();
     props.put("com.sun.management.jmxremote.port", "5000");
     vm.startManagementAgent(props);

     // detach
     vm.detach();

In this example we attach to a Java virtual machine that is identified by the process identifier 2177. Then the JMX management agent is started in the target process using the supplied arguments. Finally, the client detaches from the target VM.

A VirtualMachine is safe for use by multiple concurrent threads.

Since
1.6

Field Summary

Modifier and TypeField and Description
private volatile int
hash

private String
id

private AttachProvider
provider

Constructor Summary

AccessConstructor and Description
protected
VirtualMachine(AttachProvider
The attach provider creating this class.
provider, String
The abstract identifier that identifies the Java virtual machine.
id)

Initializes a new instance of this class.

Method Summary

Modifier and TypeMethod and Description
public static VirtualMachine

Returns:

A VirtualMachine representing the target VM.
attach(String
The abstract identifier that identifies the Java virtual machine.
id)

Attaches to a Java virtual machine.

public static VirtualMachine

Returns:

A VirtualMachine representing the target VM.
attach(VirtualMachineDescriptor
The virtual machine descriptor.
vmd)

Attaches to a Java virtual machine.

public abstract void
detach()

Detach from the virtual machine.

public boolean

Returns:

true if, and only if, the given object is a VirtualMachine that is equal to this VirtualMachine.
equals(Object
The object to which this object is to be compared
ob)

Overrides java.lang.Object.equals.

Tests this VirtualMachine for equality with another object.

public abstract Properties

Returns:

The agent properties
getAgentProperties()

Returns the current agent properties in the target virtual machine.

public abstract Properties

Returns:

The system properties
getSystemProperties()

Returns the current system properties in the target virtual machine.

public int

Returns:

A hash-code value for this virtual machine
hashCode()

Overrides java.lang.Object.hashCode.

Returns a hash-code value for this VirtualMachine.

public final String

Returns:

The identifier for this Java virtual machine.
id()

Returns the identifier for this Java virtual machine.

public static List<VirtualMachineDescriptor>

Returns:

The list of virtual machine descriptors.
list()

Return a list of Java virtual machines.

public abstract void
loadAgent(String
Path to the JAR file containing the agent.
agent, String
The options to provide to the agent's agentmain method (can be null).
options)

Loads an agent.

public void
loadAgent(String
Path to the JAR file containing the agent.
agent)

Loads an agent.

public abstract void
loadAgentLibrary(String
The name of the agent library.
agentLibrary, String
The options to provide to the Agent_OnAttach[_L] function (can be null).
options)

Loads an agent library.

public void
loadAgentLibrary(String
The name of the agent library.
agentLibrary)

Loads an agent library.

public abstract void
loadAgentPath(String
The full path of the agent library.
agentPath, String
The options to provide to the Agent_OnAttach[_L] function (can be null).
options)

Load a native agent library by full pathname.

public void
loadAgentPath(String
The full path to the agent library.
agentPath)

Load a native agent library by full pathname.

public final AttachProvider

Returns:

The provider that created this virtual machine.
provider()

Returns the provider that created this virtual machine.

public abstract String

Returns:

The String representation of the local connector's service address. The value can be parsed by the javax.management.remote.JMXServiceURL#JMXServiceURL(String) constructor.
startLocalManagementAgent()

Starts the local JMX management agent in the target virtual machine.

public abstract void
startManagementAgent(Properties
A Properties object containing the configuration properties for the agent.
agentProperties)

Starts the JMX management agent in the target virtual machine.

public String
toString()

Overrides java.lang.Object.toString.

Returns the string representation of the VirtualMachine.

Inherited from java.lang.Object:
clonefinalizegetClassnotifynotifyAllwaitwaitwait

Field Detail

hashback to summary
private volatile int hash
idback to summary
private String id
providerback to summary
private AttachProvider provider

Constructor Detail

VirtualMachineback to summary
protected VirtualMachine(AttachProvider provider, String id)

Initializes a new instance of this class.

Parameters
provider:AttachProvider

The attach provider creating this class.

id:String

The abstract identifier that identifies the Java virtual machine.

Exceptions
NullPointerException:
If provider or id is null.

Method Detail

attachback to summary
public static VirtualMachine attach(String id) throws AttachNotSupportedException, 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'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.

Parameters
id:String

The abstract identifier that identifies the Java virtual machine.

Returns:VirtualMachine

A VirtualMachine representing the target VM.

Exceptions
AttachNotSupportedException:
If the attachVirtualmachine method of all installed providers throws AttachNotSupportedException, or there aren't any providers installed.
IOException:
If an I/O error occurs
SecurityException:
If a security manager has been installed and it denies AttachPermission ("attachVirtualMachine"), or another permission required by the implementation.
NullPointerException:
If id is null.
attachback to summary
public static VirtualMachine attach(VirtualMachineDescriptor vmd) throws AttachNotSupportedException, IOException

Attaches to a Java virtual machine.

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.

Parameters
vmd:VirtualMachineDescriptor

The virtual machine descriptor.

Returns:VirtualMachine

A VirtualMachine representing the target VM.

Exceptions
AttachNotSupportedException:
If the attach provider's attachVirtualmachine throws AttachNotSupportedException.
IOException:
If an I/O error occurs
SecurityException:
If a security manager has been installed and it denies AttachPermission ("attachVirtualMachine"), or another permission required by the implementation.
NullPointerException:
If vmd is null.
detachback to summary
public abstract void detach() throws IOException

Detach from the virtual machine.

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.

Exceptions
IOException:
If an I/O error occurs
equalsback to summary
public boolean equals(Object ob)

Overrides java.lang.Object.equals.

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 Object.equals method.

Parameters
ob:Object

The object to which this object is to be compared

Returns:boolean

true if, and only if, the given object is a VirtualMachine that is equal to this VirtualMachine.

getAgentPropertiesback to summary
public abstract Properties getAgentProperties() throws 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:Properties

The agent properties

Exceptions
IOException:
If an I/O error occurs, a communication error for example, that cannot be identified as an error to indicate that the operation failed in the target VM.
AttachOperationFailedException:
If the target virtual machine is unable to complete the attach operation. A more specific error message will be given by AttachOperationFailedException#getMessage().
getSystemPropertiesback to summary
public abstract Properties getSystemProperties() throws 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 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.

Returns:Properties

The system properties

Exceptions
IOException:
If an I/O error occurs, a communication error for example, that cannot be identified as an error to indicate that the operation failed in the target VM.
AttachOperationFailedException:
If the target virtual machine is unable to complete the attach operation. A more specific error message will be given by AttachOperationFailedException#getMessage().
See Also
java.lang.System#getProperties, loadAgentLibrary, loadAgent
hashCodeback to summary
public int hashCode()

Overrides java.lang.Object.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.

Returns:int

A hash-code value for this virtual machine

idback to summary
public final String id()

Returns the identifier for this Java virtual machine.

Returns:String

The identifier for this Java virtual machine.

listback to summary
public static List<VirtualMachineDescriptor> list()

Return a list of Java virtual machines.

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.

Returns:List<VirtualMachineDescriptor>

The list of virtual machine descriptors.

loadAgentback to summary
public abstract void loadAgent(String agent, String options) throws AgentLoadException, AgentInitializationException, 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 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.

Parameters
agent:String

Path to the JAR file containing the agent.

options:String

The options to provide to the agent's agentmain method (can be null).

Exceptions
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 exception
IOException:
If an I/O error occurs
NullPointerException:
If agent is null.
loadAgentback to summary
public void loadAgent(String agent) throws AgentLoadException, AgentInitializationException, IOException

Loads an agent.

This convenience method works as if by invoking:

loadAgent(agent, null);
Parameters
agent:String

Path to the JAR file containing the agent.

Exceptions
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 exception
IOException:
If an I/O error occurs
NullPointerException:
If agent is null.
loadAgentLibraryback to summary
public abstract void loadAgentLibrary(String agentLibrary, String options) throws AgentLoadException, AgentInitializationException, 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. 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.

Parameters
agentLibrary:String

The name of the agent library.

options:String

The options to provide to the Agent_OnAttach[_L] function (can be null).

Exceptions
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.
IOException:
If an I/O error occurs
NullPointerException:
If agentLibrary is null.
See Also
com.sun.tools.attach.AgentInitializationException#returnValue()
loadAgentLibraryback to summary
public void loadAgentLibrary(String agentLibrary) throws AgentLoadException, AgentInitializationException, IOException

Loads an agent library.

This convenience method works as if by invoking:

loadAgentLibrary(agentLibrary, null);
Parameters
agentLibrary:String

The name of the agent library.

Exceptions
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.
IOException:
If an I/O error occurs
NullPointerException:
If agentLibrary is null.
loadAgentPathback to summary
public abstract void loadAgentPath(String agentPath, String options) throws AgentLoadException, AgentInitializationException, 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. 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.

Parameters
agentPath:String

The full path of the agent library.

options:String

The options to provide to the Agent_OnAttach[_L] function (can be null).

Exceptions
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.
IOException:
If an I/O error occurs
NullPointerException:
If agentPath is null.
See Also
com.sun.tools.attach.AgentInitializationException#returnValue()
loadAgentPathback to summary
public void loadAgentPath(String agentPath) throws AgentLoadException, AgentInitializationException, IOException

Load a native agent library by full pathname.

This convenience method works as if by invoking:

loadAgentPath(agentLibrary, null);
Parameters
agentPath:String

The full path to the agent library.

Exceptions
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.
IOException:
If an I/O error occurs
NullPointerException:
If agentPath is null.
providerback to summary
public final AttachProvider provider()

Returns the provider that created this virtual machine.

Returns:AttachProvider

The provider that created this virtual machine.

startLocalManagementAgentback to summary
public abstract String startLocalManagementAgent() throws IOException

Starts the local JMX management agent in the target virtual machine.

See the online documentation for Monitoring and Management Using JMX Technology for further details.

Returns:String

The String representation of the local connector's service address. The value can be parsed by the javax.management.remote.JMXServiceURL#JMXServiceURL(String) constructor.

Exceptions
IOException:
If an I/O error occurs, a communication error for example, that cannot be identified as an error to indicate that the operation failed in the target VM.
AttachOperationFailedException:
If the target virtual machine is unable to complete the attach operation. A more specific error message will be given by AttachOperationFailedException#getMessage().
Since
1.8
startManagementAgentback to summary
public abstract void startManagementAgent(Properties agentProperties) throws IOException

Starts the JMX management agent in the target virtual machine.

The configuration properties are the same as those specified on the command line when starting the JMX management agent. In the same way as on the command line, you need to specify at least the com.sun.management.jmxremote.port property.

See the online documentation for Monitoring and Management Using JMX Technology for further details.

Parameters
agentProperties:Properties

A Properties object containing the configuration properties for the agent.

Exceptions
IOException:
If an I/O error occurs, a communication error for example, that cannot be identified as an error to indicate that the operation failed in the target VM.
AttachOperationFailedException:
If the target virtual machine is unable to complete the attach operation. A more specific error message will be given by AttachOperationFailedException#getMessage().
IllegalArgumentException:
If keys or values in agentProperties are invalid.
NullPointerException:
If agentProperties is null.
Since
1.8
toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Returns the string representation of the VirtualMachine.

Returns:String

Doc from java.lang.Object.toString.

a string representation of the object