• Improved Instrumentation API
• Improved JVM Tool Interface
• Improved Management and JMX APIs
• JConsole GUI makeover
• JConsole plug-ins and the JConsole API
Dynamic Attach and the Attach API
HotSpot virtual machines contain instrumentation that JMX-compliant tools like JConsole access via the JMX agent to monitor memory consumption, class loading, and so on. Prior to Java SE 6, you needed to start an application with the com.sun.
management.jmxremotesystem property, which was often specified on the command line, to locally monitor the virtual machine’s instrumentation via JConsole (or a similar tool).
This property caused the JMX agent and a connector server to start up in the applica- tion’s virtual machine, so that JConsole could connect to this virtual machine without needing to prompt the user for connection details. This is known as local monitoring, because JConsole must run on the same machine (and belong to the same user) as the application. The following command line demonstrates running an application under Java 5 with com.sun.management.jmxremote:
221
C H A P T E R 7
java -Dcom.sun.management.jmxremote BuggyApp
Behind the scenes, JConsole uses a javax.management.remote.JMXConnector–based client to establish a connection to a javax.management.remote.JMXConnectorServer–based connector server running in the target virtual machine (the virtual machine in which the application runs). Before Java SE 6, if the application was not started with the JMX agent (because com.sun.management.jmxremotewas not specified), a JMXConnectorServer–based connector server would not be running, and JConsole could not make a connection.
Starting with Java SE 6, JConsole overcomes this problem by using a virtual machine mechanism to start the JMX agent in the target virtual machine. This mechanism, which is known as dynamic attach, is supported by Sun’s new Attach API (http://java.sun.com/
javase/6/docs/technotes/guides/attach/index.html).
The Attach API consists of two packages, which are stored in tools.jar:
• com.sun.tools.attach: This package provides six classes for use in attaching to virtual machines and loading tool agents. These classes are described in Table 7-1.
• com.sun.tools.attach.spi: This package provides the AttachProviderclass, which virtual machine developers use to support dynamic attach and the Attach API on their machines.
Although Sun generally discourages working with its “com.sun.*” packages, you need to work with these packages to access the Attach API.
Table 7-1.com.sun.tools.attach Classes
Class Description
AgentInitializationException An agent did not initialize within a target virtual machine.
AgentLoadException An agent could not be loaded into a target virtual machine.
AttachNotSupportedException The target virtual machine does not have a compatible AttachProvider.
AttachPermission The permission checked by a SecurityManager(if present) when attempting to attach to a target virtual machine.
VirtualMachine A target virtual machine representation.
VirtualMachineDescriptor A description of a target virtual machine. This description consists of an identifier (usually a target virtual machine’s process identifier) returned via the public String id() method, an AttachProviderreference (for use in attaching to a target virtual machine) returned via the public AttachProvider provider()method, and a display name (a human-readable string that is useful in building a GUI-based list of virtual machine names) returned via the public String displayName()method.
The VirtualMachineclass is the entry point into the Attach API. Its public static VirtualMachine attach(String id)method lets you attach the current virtual machine to a target virtual machine. The idparameter is an abstract identifier for the target virtual machine, usually its process identifier. This method returns a target VirtualMachine instance, or it throws one of the following exceptions:
• AttachNotSupportedException: The attach()method’s argument does not identify a valid target virtual machine, or the target virtual machine does not have a com- patible AttachProvider.
• java.io.IOException: An I/O-related problem has occurred.
• NullPointerException: The nullargument was passed to id.
• SecurityException: A SecurityManageris present and denies AttachPermissionor some other AttachProviderimplementation-specific permission.
This attach()method is useful in those tools where users specify identifiers (perhaps obtained by the jpsprocess status tool) on tool command lines. If you prefer to have the user choose a target machine from a GUI list, and then attach to the target, you will want to work with the public static List<VirtualMachineDescriptor> list()and public static VirtualMachine attach(VirtualMachineDescriptor vmd)methods. These methods also can throw the exceptions shown in the preceding list.
In addition to the attach()and list()methods, VirtualMachinespecifies public abstract void detach(), to detach the current virtual machine from a target virtual machine; public final String id()to return the target virtual machine’s identifier; and several other methods, such as those described in Table 7-2. I will demonstrate most of these methods in upcoming sample applications that interact with target virtual machines.
Table 7-2.Additional VirtualMachine Methods
Method Description
public abstract Properties Returns the target virtual machine’s current agent properties, getAgentProperties() which are typically used to store communication end points
and other configuration details. This method includes only those properties whose keys and values are Strings.
public abstract Properties Returns the target virtual machine’s system properties, which getSystemProperties() are useful for deciding which agent to load into the target
virtual machine. Only properties with String-based keys and values are included.
Continued
public abstract void Loads an agent into the target virtual machine. The argument loadAgent(String agent, passed to agentis the path and name of the agent’s JAR file String options) relative to the target virtual machine’s file system. The JAR file is
added to the target virtual machine’s system classpath, and the agent class’s agentmain()method is invoked with the specified options. The agent class is identified by the Agent-Class attribute in the JAR file’s manifest. The loadAgent()method completes after agentmain()completes. An AgentLoadException is thrown if the agent does not exist or cannot be started. An AgentInitializationExceptionis thrown if agentmain()throws an exception. An IOException
is thrown if some I/O-related problem occurs. A
NullPointerExceptionis thrown if nullis passed to agent.
public void A convenience method that invokes the previous loadAgent() loadAgent(String agent) method by passing nullto options.