Module jdk.attach
Package com.sun.tools.attach

Class VirtualMachine

java.lang.Object
com.sun.tools.attach.VirtualMachine
public abstract class VirtualMachine extends 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, 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