Serviceability in the J2SE Repository

This page describes the Serviceability technologies in the J2SE repository. These technologies use the following serviceability technologies in the HotSpot repository:

Java Virtual Machine Tools Interface (JVM TI)
HotSpot Monitoring and Management Interface (jmm.h)
Dynamic attach
Serviceability Agent
jvmstat performance counters (sometimes called perfdata)

Please see HotSpot Serviceability for more information on these technologies in the HotSpot repository.

The following table shows where the Serviceability technologies reside in the J2SE repository and in the binary release, and contains links to user level information and building/implementation notes. The building/implementation notes are not intended to be complete documentation but just some high level notes that will help the reader get started understanding how these technologies work.
For JPDA, the reader is advised to read the User Guide to learn the architecture of JPDA before reading the build/implementation notes.

Notes:

Each row represents both the API for the technology (if there is one), and the implementation of the technology.
In the Binary Location column, a path that starts with jdk means the component is contained in the jdk but not in the jre. A component whose path starts with jre is contained in both the jdk and the jre.
Paths that begin with 'hotspot' are in the HotSpot repository instead of the J2SE repository

Technology	Source Location	Binary Location	More Info
JPDA-Java Platform Debugger Architecture	---	---	Home Page Bugs
JDI-Java Debug Interface	j2se/src/share/classes/com/sun/jdi/ j2se/src/share/classes/com/sun/tools/jdi/ j2se/build/<arch>/gensrc/com/sun/tools/jdi/JDWP.java j2se/test/com/sun/jdi/ j2se/make/jpda/front/	jdk/lib/tools.jar	User Guide Bugs \| grep -i jdi
JDWP-Java Debug Wire Protocol	j2se/src/share/classes/com/sun/tools/jdwpgen/jdwp.spec j2se/src/share/classes/com/sun/tools/jdwpgen/.java j2se/src/share/back/ j2se/src/share/javavm/export/jdwpTransport.h j2se/build/<arch>/gensrc/com/sun/tools/jdi/JDWP.java j2se/build/<arch>*/tmp/jpda/com.sun.tools.jdwpgen/\ jdwp/JDWPCommands.h j2se/make/jpda/back/ j2se/make/jpda/jdwp/ j2se/make/jpda/jdwpgen/	jre/lib/<arch>/libjdwp.so jre/bin/jdwp.dll	User Guide Bugs \| grep -i jdwp
Transports / Connectors	j2se/src/solaris/transport/ j2se/src/windows/transport/ j2se/src/windows/classes/com/sun/tools/jdi/ j2se/src/share/transport/shmem/ j2se/src/share/transport/socket/ j2se/src/share/native/com/sun/tools/jdi/SharedMemory* j2se/make/jpda/transport/	jre/lib/<arch>/libdt_socket.so jre/bin/dt_shmem.dll jre/bin/dt_socket.dll	User Guide
JVM TI- Java Virtual Machine Tools Interface	j2se/src/share/javavm/export/jvmti.h	libjvm.so jvm.dll	User Guide Hotspot Info Bugs
jdb: See demo entry below	---	---	---
Other APIs
Profiling and Bytecode Instrumentation	j2se/src/share/classes/java/lang/instrument/ j2se/src/share/classes/sun/instrument/ j2se/src/share/instrument/ j2se/make/java/lang/instrument/ j2se/test/java/lang/instrument/ j2se/test/sun/instrument/	jre/lib/<arch>/libinstrument.so jre/bin/instrument.dll	User Guide Bugs \| grep -i instrument
Java Management Extension (JMX)	j2se/src/share/classes/javax/management/ j2se/src/share/classes/com/sun/jmx/	jre/lib/rt.jar	Home Page Bugs
Monitoring and Management	j2se/src/share/classes/java/lang/management/ j2se/src/share/classes/com/sun/management/ j2se/src/share/classes/sun/management/ j2se/src/share/lib/management/ j2se/src/share/native/sun/management/ j2se/src/solaris/classes/com/sun/management/ j2se/src/solaris/classes/sun/management/ j2se/src/solaris/native/com/sun/management/ j2se/src/solaris/native/sun/management/ j2se/src/windows/classes/com/sun/management/ j2se/src/windows/classes/sun/management/ j2se/src/windows/native/com/sun/management/ j2se/src/windows/native/sun/management/ j2se/src/share/javavm/export/jmm.h j2se/make/java/lang/management/ j2se/test/java/lang/management/ j2se/test/com/sun/management/ j2se/test/sun/management/	jre/lib/rt.jar jre/lib/management-agent.jar jre/lib/management jre/lib/<arch>/libmanagement.so jre/bin/management.dll	Home Page Hotspot Info Bugs HotSpot Bugs
NPT - Native Platform Toolkit	j2se/src/share/npt/ j2se/src/solaris/npt/ j2se/src/windows/npt/ j2se/make/java/npt/	jre/lib/<arch>/libnpt.so jre/bin/npt.dll	j2se/src/share/npt/method.html
Dynamic Attach Mechanism	j2se/src/share/classes/com/sun/tools/attach/ j2se/src/share/classes/sun/tools/attach/ j2se/src/solaris/classes/sun/tools/attach/ j2se/src/solaris/native/sun/tools/attach/LinuxVirtualMachine.c j2se/src/solaris/native/sun/tools/attach/SolarisVirtualMachine.c j2se/src/windows/classes/sun/tools/attach/ j2se/src/windows/native/sun/tools/attach/ j2se/test/com/sun/tools/attach/	jdk/lib/tools.jar jdk/jre/lib/<arch>/libattach.so jdk/jre/bin/attach.dll	User Guide Hotspot Info Bugs \| grep -i attach
Jvmstat Performance Counters	j2se/src/share/classes/sun/jvmstat/monitor/ j2se/src/share/classes/sun/jvmstat/perfdata/	jdk/lib/tools.jar	Javadoc Hotspot Info Bugs \| grep -i jvmstat HotSpot Bugs
ServiceabilityAgent	All the SA code is currently in the HotSpot repository, in the agent/ directory.	jre/lib/<arch>/libsaproc.so jdk/lib/sa-jdi.jar As of JDK 6, SA is not released on Windows	Hotspot Info Bugs \| grep SA
Demos and sample code
jdb	j2se/src/share/classes/com/sun/tools/example/debug/tty/ j2se/make/jpda/bdi/ j2se/make/jpda/expr/ j2se/make/jpda/tty/ j2se/make/jpda/gui/	jdk/bin/jdb jdk/demo/jpda/examples.jar	User Guide Bugs \| grep -i tty
hprof	j2se/src/*/demo/jvmti/hprof/ j2se/src/share/classes/sun/tools/hprof/Tracker.java j2se/make/java/java_hprof_demo	jdk/demo/jvmti/hprof jre/lib/<arch>/libhprof.so jre/bin/hprof.dll jre/lib/jvm.hprof.txt	jdk/demo/jvmti/hprof/src/manual.html Bugs
java_crw_demo	j2se/src/share/demo/jvmti/java_crw_demo/ j2se/src/share/javavm/export/classfile_constants.h j2se/make/java/java_crw_demo/	jdk/demo/jvmti/java_crw_demo	jdk/demo/jvmti/\ java_crw_demo/README.txt
JVM TI demos	j2se/src/share/demo/jvmti/ j2se/make/mkdemo/jvmti/	jdk/demo/jvmti/	jdk/demo/NAME/README.txt
JConsole plugin demo	j2se/src/share/demo/scripting/jconsole-plugin/	jdk/demo/scripting/jconsole-plugin/	jdk/demo/jconsole-plugin/README.txt
Management demos: FullThreadDump JTop MemoryMonitor VerboseGC	j2se/src/share/demo/management/*	jdk/demo/nbproject/management/* jdk/demo/management/*	jdk/demo/management/*/README.txt
Serviceability Tools
jconsole	j2se/src/share/classes/sun/tools/jconsole/ j2se/src/share/classes/com/sun/tools/jconsole/ j2se/make/sun/jconsole/ j2se/make/netbeans/jconsole/ j2se/make/netbeans/jconsole/README	jdk/lib/jconsole.jar jdk/bin/jconsole	Man page Bugs
jdb - See jdb demo entry above	---	---	---
jhat	jdk/src/share/classes/com/sun/tools/hat/ j2se/make/sun/hat/	jdk/bin/jhat	Man page Bugs \| grep jhat
jinfo	jdk/src/share/classes/sun/tools/jinfo/ j2se/make/sun/jinfo/	jdk/bin/jinfo	Man page Bugs \| grep jinfo
jmap	jdk/src/share/classes/sun/tools/jmap/ j2se/make/sun/jmap/	jdk/bin/jmap	Man page Bugs \| grep jmap
jps	jdk/src/share/classes/sun/tools/jps/ j2se/make/sun/jps/	jdk/bin/jps	Man page Bugs \| grep jps
jcontrol	deploy/src/plugin/solaris/controlpanel/ deploy/src/plugin/win32/controlpanel/ deploy/src/common/share/classes/com/sun/deploy/panel/	jre/bin/jcontrol jre/lib/deploy.jar jre/bin/javacpl.exe jre/bin/javacpl.cpl	User Guide
jsadebugd	hotspot/agent/src/share/classes/sun/jvm/hotspot/jdi/\ SADebugServer.java j2se/make/sun/jsadebugd/	jdk/bin/jsadebugd	Man page
jstack	jdk/src/share/classes/sun/tools/jstack/ j2se/make/sun/jstack/	jdk/bin/jstack	Man page Bugs \| grep jstack
jstat	j2se/src/share/classes/sun/tools/jstat/ j2se/make/sun/jstat/	jdk/bin/jstat	Man page Bugs \| grep jstat
jstatd	jdk/src/share/classes/sun/tools/jstatd/ j2se/make/sun/jstatd/	jdk/bin/jstatd	Man page

Build and Implementation Notes

JDI-Java Debug Interface and the Front-end

The Java Debug Interface consists of the API in com.sun.jdi and the implementation in com.sun.tools.jdi. The API is an optional part of the Java platform. Please refer to the JPDA documentation for more information about how JDI and its implementation fits into JPDA, and how requests and events flow through JPDA. Please see JPDA Front-end Threads for information about the thread structure of the front-end.

The front-end can register to receive events on its own. It currently needs to keep track of classes that are loaded so it registers to receive class prepare events and class unload events. These events are handled by the front-end's Internal Event Handler thread.

The front-end uses a class named JDWP whose .java file is generated by the jdwpgen program, see below. JDWP contains all the methods that the front-end calls to create JDWP command packets. These methods then call transport methods to actually send the packets down the wire to the back-end.

The front-end also contains the code for the default connectors and contains the Java code for the socket transport. The socket transport uses the socket support in the JDK libraries so no native code is needed in the front-end.

This is not true of the shared memory transport, so it is implemented in native code which executes as part of the front-end. Note that the shared memory transport is only available on Windows, and so its code is in a Windows specific directory. See the Transports and Connectors section for more information.

JDWP-Java Debug Wire Protocol and the Back-end

File jdwp.spec contains the base definition of JDWP. During the build of JPDA, the jdwpgen program is built and is then called to process jdwp.spec. This creates three files:

jdwp.html - the JDWP specification
JDWP.java - the class used by the front-end to create and write JDWP packets
JDWPCommands.h - the JDWP constants needed by the C code in the back-end.

JDWP and JDI are generally isomorphic, but there are exceptions. In addition, for each front-end file, eg, VirtualMachineImpl.java, there tends to be a back-end file, eg, VirtualMachineImpl.c that contains the code that handles the JDWP commands that originate from the JDI methods defined in the corresponding front-end file.

The structure of the JDWP packets for the various commands is embedded in the back-end files. For example to read the redefineClasses command, back-end file VirtualMachineImpl.c does this:

static jboolean 
redefineClasses(PacketInputStream *in, PacketOutputStream *out) 
{
    jvmtiClassDefinition *classDefs;
    jboolean ok = JNI_TRUE;
    jint classCount;
    jint i;
    JNIEnv *env;

    if (gdata->vmDead) {
        /* quietly ignore */                
        return JNI_TRUE;
    }

    classCount = inStream_readInt(in);
    if (inStream_error(in)) {
        return JNI_TRUE;
    }
    if ( classCount == 0 ) {
        return JNI_TRUE;
    }
    /*LINTED*/
    classDefs = jvmtiAllocate(classCount*(int)sizeof(jvmtiClassDefinition));
    if (classDefs == NULL) {
        outStream_setError(out, JDWP_ERROR(OUT_OF_MEMORY));
        return JNI_TRUE;
    }
    /*LINTED*/
    (void)memset(classDefs, 0, classCount*sizeof(jvmtiClassDefinition));
  
    env = getEnv();

    for (i = 0; i < classCount; ++i) {
        int byteCount;
        unsigned char * bytes;
        jclass clazz;
        
        clazz = inStream_readClassRef(env, in);
        if (inStream_error(in)) {
            ok = JNI_FALSE;
            break;
        }
        byteCount = inStream_readInt(in);
        if (inStream_error(in)) {
            ok = JNI_FALSE;
            break;
        }
        if ( byteCount <= 0 ) {
            outStream_setError(out, JDWP_ERROR(INVALID_CLASS_FORMAT));
            ok = JNI_FALSE;
            break;
        }
        bytes = (unsigned char *)jvmtiAllocate(byteCount);
        if (bytes == NULL) {
            outStream_setError(out, JDWP_ERROR(OUT_OF_MEMORY));
            ok = JNI_FALSE;
            break;
        }        
        (void)inStream_readBytes(in, byteCount, (jbyte *)bytes);
        if (inStream_error(in)) {
            ok = JNI_FALSE;
            break;
        }

The back-end calls JVM TI functions to actually interrogate the JVM. To do this, it uses file jvmti.h which defines JVM TI. See JVM TI for more information on jvmti.h

See JPDA Back-end Threads for information about the threads used in the back-end.

JPDA Transports and Connectors

Currently, each JPDA transport is wrapped in a JDPA connector. These all reside in .jar files and are discovered by the VirtualMachineManagerImpl constructor which is called from class com.sun.jdi.Bootstrap during front-end initialization. See Service Provider Interfaces for information on adding custom connectors/transports to a JPDA installation.

JVM TI

The code for JVM TI is in the HotSpot repository; please see JVM TI.

The HotSpot build process creates interface file jvmti.h which is used by JVM TI agents such as the JPDA back-end. jvmti.h is copied from the HotSpot build area and checked into the J2SE repository whenever changes are made to the interface. This file contains a JVM TI version number which is compiled into the back-end and is checked against the JVM TI version that is compiled into HotSpot during back-end startup.

Profiling and Instrumentation

java.lang.instrument uses a native JVM TI agent called the JPLISAgent. The JPLISAgent manages the initialization of all the Java programming language Agents. It also supports the native method bridge between the JPLIS and the JVM TI. It maintains a single JVMTI Env that all JPL agents share. It parses command line requests and creates individual Java agents. The code for this agent is contained in j2se/src/share/instrument. At runtime, it resides in libinstrument.so/instrument.dll and is dynamically loaded by code in sun.instrument.InstrumentationImpl.

Monitoring and Management

Java SE contains a JMX MBean Server called the Platform MBean Server (see java.lang.management.ManagementFactory.getPlatformMBeanServer) which can be used to make MBeans available for remote access. The Platform MBean Server is started by code in j2se/src/share/classes/sun/management/Agent.java. This class is named as the Premain-class and Agent-class in JPLIS agent jre/lib/management-agent.jar which allows the agent (and thus the Platform MBean Server) to be started dynamically via the loadAgent method of Dynamic Attach. The agent can also be started at JVM startup time by use of the -Dcom.sun.management.jmxremote or the -Dcom.sun.management.snmp command line options on the java command.

The classes in java.lang.managment define a set of MBeans that are used to access information from the JVM and the operating system upon which it is running. These MBeans are registered with the Platform MBean Server when it is started.

The platform MBeans are implemented by classes in sun.management. These classes contain native methods that call functions defined in jmm.h to extract the required information from the JVM. jmm.h is implemented by the Java Virtual Machine.

See Monitoring and Management in HotSpot for more information.
See JMX- Java Management Extensions API for information about JMX.

Dynamic Attach Mechanism

This is a Sun extension that allows a tool to 'attach' to another process running Java code and launch a JVM TI agent or a java.lang.instrument agent in that process. This also allows the system properties to be obtained from the target JVM.

The Sun implementation of this API also includes some HotSpot specific methods that allow additional information to be obtained from HotSpot:

The ctrl-break output from the local JVM
The ctrl-break output from the remote JVM
A dump of the heap
A histogram showing the number of instances of the classes loaded in the target JVM. Either all instances or just 'live' instances can be counted.
The value of a manageable command line flag. Such flags can also be set.

See j2se/src/share/classes/sun/tools/attach/HotSpotVirtualMachine.java for more information.

Dynamic attach is used by jconsole jstack jmap jinfo

Jvmstat Performance Counters

Hotspot exports the performance counters to a memory area that is mapped to a file. The jvmstat classes in the J2SE repository use java.io to read this data and make it available to callers. For examples of the use of the sun.jvmstat API, see:

j2se/src/share/classes/sun/tools/jps/Jps.java
j2se/src/share/classes/sun/tools/jstat/Jstat.java

This data is used by Dynamic Attach, jconsole, jps, jstat

Serviceability Agent

Serviceability Agent components are built as part of the standard build of the HotSpot repository. These components are:

libsaproc.so: this is the native code component of SA.
sa-jdi.jar: This is contains the Java classes of SA. It includes an implementation of JDI which allows JDI clients to do read-only debugging on core files and hung processes.

These two files are copied from the HotSpot build area to the JDK build area during a control build (a control build is a build of the control repository which first builds HotSpot and then builds the J2SE repository, so that the files built by the HotSpot build are available to the J2SE build.)

SA is used by jinfo, jmap, jstack

NOTE: The Serviceability Agent and the technologies that use it are not currently included in JDK releases on the Windows platforms.

jconsole

JConsole uses dynamic attach to show monitorable Java processes, and to attach to them. It uses JMX to obtain information from a monitored JVM. Please see the jconsole tool page for more information on JConsole.

jhat

jhat was derived from hat.java.net. The jhat source directory contains a build.xml file that can be used by ant to just build jhat.

jinfo

jinfo uses dynamic attach for the -flag option and uses Serviceability Agent for the -flags and -sysprops options.

jmap

jmap uses dynamic attach for the -dump and -histo options and Serviceability Agent for the other options. However, the -F option causes jmap to use SA for -dump and -histo also.

jps

jps uses the jvmstat mechanism to obtain the list of monitorable Java processes.

jcontrol

Note that the source for jcontrol is in the deploy respository instead of the J2SE repository.

jsadebugd

jsadebugd is a Serviceability Agent 'server' that allows SA based tools to observe processes on remote machines. The code for jsadebugd resides in the HotSpot repository with the rest of the SA code. The J2SE repository just contains a makefile that creates the wrapper script that runs the sun.jvm.hotspot.jdi.SADebugServer class.

jstack

jstack uses dynamic attach to print a non-mixed mode stack trace (ie, no native frames) and Serviceability Agent to do the rest.

jstat

jstat (formerly jvmstat) is the primary user interface to the jvmstat performance counters. You can find the mapping between the options shown by 'jstat -options' and the names of the performance counters in the file j2se/src/share/classes/sun/tools/jstat/resources/jstat_options

jstat contains several unpublished features:

You can create your own output display by creating $HOME/.jvmstat/jstat_options containing data in the form of the installed jstat_options file.
'jstat -snap pid' will show name/value pairs for all the counters. To see Sun-internal counters, add option -J-Djstat.showUnsupported=true. Note these internal counters are even more unsupported than is jstat itself.
See file j2se/src/share/classes/sun/tools/jstat/Arguments.java for more undocumented options

jstatd

jstatd starts a server that allows jstat to access performance counters from a remote machine via Java Remote Method Invocation.

Last Modified: 06/29/07