Java Doc for VirtualMachine.java in  » 6.0-JDK-Modules-com.sun » tools » com » sun » tools » attach » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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 VirtualMachine.attach(String) 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 VirtualMachine.attach(VirtualMachineDescriptor) attach method with a com.sun.tools.attach.VirtualMachineDescriptor VirtualMachineDescriptor obtained from the list of virtual machine descriptors returned by the VirtualMachine.list list method. Once a reference to a virtual machine is obtained, the VirtualMachine.loadAgent loadAgent , VirtualMachine.loadAgentLibrary loadAgentLibrary , and VirtualMachine.loadAgentPath loadAgentPath methods are used to load agents into target virtual machine. The VirtualMachine.loadAgent loadAgent method is used to load agents that are written in the Java Language and deployed in a java.util.jar.JarFile JAR file . (See java.lang.instrument for a detailed description on how these agents are loaded and started). The VirtualMachine.loadAgentLibrary loadAgentLibrary and VirtualMachine.loadAgentPath loadAgentPath 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 java.lang.System.getProperties 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.

This method obtains the list of attach providers by invoking the com.sun.tools.attach.spi.AttachProvider.providersAttachProvider.providers() method.

This method first invokes the com.sun.tools.attach.VirtualMachineDescriptor.provider provider() method of the given virtual machine descriptor to obtain the attach provider.

After detaching from the virtual machine, any further attempt to invoke operations on that virtual machine will cause an java.io.IOExceptionIOException to be thrown.

If the given object is not a VirtualMachine then this method returns false.

The target virtual machine can maintain a list of properties on behalf of agents.

This method returns the system properties in the target virtual machine.

The agent provided to this method is a path name to a JAR file on the file system of the target virtual machine.

A JVM TI client is called an agent.

A JVM TI client is called an agent.

This method obtains the list of attach providers by invoking the com.sun.tools.attach.spi.AttachProvider.providersAttachProvider.providers() method. It then iterates overs the list and invokes each provider's com.sun.tools.attach.spi.AttachProvider.attachVirtualMachine(java.lang.String)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 com.sun.tools.attach.AttachNotSupportedException 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 com.sun.tools.attach.spi.AttachProvider.providersAttachProvider.providers() returns an empty list.

This method first invokes the com.sun.tools.attach.VirtualMachineDescriptor.provider provider() method of the given virtual machine descriptor to obtain the attach provider. It then invokes the attach provider's com.sun.tools.attach.spi.AttachProvider.attachVirtualMachine(VirtualMachineDescriptor)attachVirtualMachine to attach to the target VM.
Parameters:
  vmd - The virtual machine descriptor. A VirtualMachine representing the target VM.
throws:
  SecurityException - If a security manager has been installed and it deniescom.sun.tools.attach.AttachPermission AttachPermission("attachVirtualMachine"), or another permissionrequired by the implementation.
throws:
  AttachNotSupportedException - If the attach provider's attachVirtualmachinethrows AttachNotSupportedException.
throws:
  IOException - If an I/O error occurs
throws:
  NullPointerException - If vmd is null.

After detaching from the virtual machine, any further attempt to invoke operations on that virtual machine will cause an java.io.IOExceptionIOException to be thrown. If an operation (such as VirtualMachine.loadAgentloadAgent 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.

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 VirtualMachineDescriptor.id identifiers are equal.

This method satisfies the general contract of the java.lang.Object.equals(Object) Object.equals method.

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. The agent properties
throws:
  IOException - If an I/O error occurs

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 java.lang.System.getProperties 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 VirtualMachine.loadAgent loadAgent , or VirtualMachine.loadAgentLibrary loadAgentLibrary . For example, the java.home or user.dir properties might be use to create the path to the agent library or JAR file. The system properties
throws:
  IOException - If an I/O error occurs
See Also:   java.lang.System.getProperties
See Also:   VirtualMachine.loadAgentLibrary
See Also:   VirtualMachine.loadAgent

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 com.sun.tools.attach.spi.AttachProvider.listVirtualMachineslistVirtualMachines method of all installed com.sun.tools.attach.spi.AttachProvider attach providers . If there are no Java virtual machines known to any provider then an empty list is returned. The list of virtual machine descriptors.

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 - Path to the JAR file containing the agent.
Parameters:
  options - The options to provide to the agent's agentmainmethod (can be null).
throws:
  AgentLoadException - If the agent does not exist, or cannot be started in the mannerspecified in the java.lang.instrument specification.
throws:
  AgentInitializationException - If the agentmain throws an exception
throws:
  IOException - If an I/O error occurs
throws:
  NullPointerException - If agent is null.

This convenience method works as if by invoking:

VirtualMachine.loadAgent(String,String) loadAgent (agent, null);

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 the Agent_OnAttach function as specified in the JVM Tools Interface specification. Note that the Agent_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 the Agent_OnAttach function in the agent library returns an error then an com.sun.tools.attach.AgentInitializationException is thrown. The return value from the Agent_OnAttach can then be obtained by invoking the com.sun.tools.attach.AgentInitializationException.returnValue returnValue method on the exception.

This convenience method works as if by invoking:

VirtualMachine.loadAgentLibrary(String,String) loadAgentLibrary (agentLibrary, null);

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 the Agent_OnAttach function as specified in the JVM Tools Interface specification. Note that the Agent_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. Unlike VirtualMachine.loadAgentLibrary loadAgentLibrary , the library name is not expanded in the target virtual machine.

If the Agent_OnAttach function in the agent library returns an error then an com.sun.tools.attach.AgentInitializationException is thrown. The return value from the Agent_OnAttach can then be obtained by invoking the com.sun.tools.attach.AgentInitializationException.returnValue returnValue method on the exception.

This convenience method works as if by invoking:

VirtualMachine.loadAgentPath(String,String) loadAgentPath (agentLibrary, null);