sun.tools.attach

Class HotSpotVirtualMachine

java.lang.Object

com.sun.tools.attach.VirtualMachine

sun.tools.attach.HotSpotVirtualMachine

Direct Known Subclasses:

BsdVirtualMachine, LinuxVirtualMachine, SolarisVirtualMachine, WindowsVirtualMachine

public abstract class HotSpotVirtualMachine
extends VirtualMachine

Method Summary

Modifier and Type	Method and Description
InputStream	dumpHeap(Object... args)
InputStream	executeJCmd(String command)
Properties	getAgentProperties() Returns the current agent properties in the target virtual machine.
Properties	getSystemProperties() Returns the current system properties in the target virtual machine.
InputStream	heapHisto(Object... args)
void	loadAgent(String agent, String options) Loads an agent.
void	loadAgentLibrary(String agentLibrary, String options) Loads an agent library.
void	loadAgentPath(String agentLibrary, String options) Load a native agent library by full pathname.
void	localDataDump()
InputStream	printFlag(String name)
InputStream	remoteDataDump(Object... args)
InputStream	setFlag(String name, String value)
String	startLocalManagementAgent() Starts the local JMX management agent in the target virtual machine.
void	startManagementAgent(Properties agentProperties) Starts the JMX management agent in the target virtual machine.

Methods inherited from class com.sun.tools.attach.VirtualMachine

attach, attach, detach, equals, hashCode, id, list, loadAgent, loadAgentLibrary, loadAgentPath, provider, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Method Detail

loadAgentLibrary

public void loadAgentLibrary(String agentLibrary,
                             String options)
                      throws AgentLoadException,
                             AgentInitializationException,
                             IOException

Description copied from class: VirtualMachine

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 AgentInitializationException is thrown. The return value from the Agent_OnAttach[_L] can then be obtained by invoking the returnValue method on the exception.

Specified by:

loadAgentLibrary in class VirtualMachine

Parameters:

agentLibrary - The name of the agent library.

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

Throws:

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

See Also:

AgentInitializationException.returnValue()

loadAgentPath

public void loadAgentPath(String agentLibrary,
                          String options)
                   throws AgentLoadException,
                          AgentInitializationException,
                          IOException

Description copied from class: VirtualMachine

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 AgentInitializationException is thrown. The return value from the Agent_OnAttach[_L] can then be obtained by invoking the returnValue method on the exception.

Specified by:

loadAgentPath in class VirtualMachine

Parameters:

agentLibrary - The full path of the agent library.

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

Throws:

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

See Also:

AgentInitializationException.returnValue()

loadAgent

public void loadAgent(String agent,
                      String options)
               throws AgentLoadException,
                      AgentInitializationException,
                      IOException

Description copied from class: VirtualMachine

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.

Specified by:

loadAgent in class VirtualMachine

Parameters:

agent - Path to the JAR file containing the agent.

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

Throws:

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

getSystemProperties

public Properties getSystemProperties()
                               throws IOException

Description copied from class: VirtualMachine

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.

Specified by:

getSystemProperties in class VirtualMachine

Returns:

The system properties

Throws:

AttachOperationFailedException - If the target virtual machine is unable to complete the attach operation. A more specific error message will be given by Throwable.getMessage().

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.

See Also:

System.getProperties(), VirtualMachine.loadAgentLibrary(java.lang.String, java.lang.String), VirtualMachine.loadAgent(java.lang.String, java.lang.String)

getAgentProperties

public Properties getAgentProperties()
                              throws IOException

Description copied from class: VirtualMachine

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.

Specified by:

getAgentProperties in class VirtualMachine

Returns:

The agent properties

Throws:

AttachOperationFailedException - If the target virtual machine is unable to complete the attach operation. A more specific error message will be given by Throwable.getMessage().

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.

startManagementAgent

public void startManagementAgent(Properties agentProperties)
                          throws IOException

Description copied from class: VirtualMachine

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.

Specified by:

startManagementAgent in class VirtualMachine

Parameters:

agentProperties - A Properties object containing the configuration properties for the agent.

Throws:

AttachOperationFailedException - If the target virtual machine is unable to complete the attach operation. A more specific error message will be given by Throwable.getMessage().

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.

startLocalManagementAgent

public String startLocalManagementAgent()
                                 throws IOException

Description copied from class: VirtualMachine

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.

Specified by:

startLocalManagementAgent in class VirtualMachine

Returns:

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

Throws:

AttachOperationFailedException - If the target virtual machine is unable to complete the attach operation. A more specific error message will be given by Throwable.getMessage().

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.

localDataDump

public void localDataDump()
                   throws IOException

Throws:

IOException

remoteDataDump

public InputStream remoteDataDump(Object... args)
                           throws IOException

Throws:

IOException

dumpHeap

public InputStream dumpHeap(Object... args)
                     throws IOException

Throws:

IOException

heapHisto

public InputStream heapHisto(Object... args)
                      throws IOException

Throws:

IOException

setFlag

public InputStream setFlag(String name,
                           String value)
                    throws IOException

Throws:

IOException

printFlag

public InputStream printFlag(String name)
                      throws IOException

Throws:

IOException

executeJCmd

public InputStream executeJCmd(String command)
                        throws IOException

Throws:

IOException