Java Platform Debugger Architecture

Java Virtual Machine Tool Interface (JVMTI)

JVMTI is the superceder of JVMDI and the Java Virtual Machine Profiler Interface (JVMPI). JVMTI contains all the functionality of both JVMDI and JVMPI, plus new functions. JVMTI was added as part of J2SE 5.0. In future releases, the JVMDI and JVMPI interfaces will no longer be offered, and JVMTI will be the only option available.

A service program, called QJVAJVMTI, which resides in the QSYS library, supports the JVMTI functions.

For more information about implementing JVMTI, see the JVMTI Reference page at the Sun Microsystems, Inc. Web site.

Java Virtual Machine Debug Interface

In Java 2 SDK (J2SDK), Standard Edition, version 1.2 or higher, the Java Virtual Machine Debug Interface (JVMDI) is part of Sun Microsystems, Inc. platform application program interfaces (APIs). JVMDI allows anyone to write a Java debugger for an iSeries server in iSeries C code. The debugger does not need to know the internal structure of the Java virtual machine since it uses JVMDI interfaces. JVMDI is the lowest-level interface in JPDA that is closest to the Java virtual machine.

The debugger runs in the same multi-thread capable job as the Java virtual machine. The debugger uses Java Native Interface (JNI) Invocation APIs to create a Java virtual machine. It then places a hook at the beginning of a user class main method and calls the main method. When the main method begins, the hook is hit and debugging begins. Typical debug facilities are available, such as setting breakpoints, stepping, displaying variables, and changing variables.

The debugger handles communication between the job where the Java virtual machine is running and a job handling the user interface. This user interface is either on your iSeries server or another system.

A service program, called QJVAJVMDI that resides in the QSYS library, supports the JVMDI functions.

Java Debug Wire Protocol

The Java Debug Wire Protocol (JDWP) is a defined communication protocol between a debugger process and the JVMDI/JVMTI. JDWP can be used from either a remote system or over a local socket. It is one layer removed from the JVMDI/JVMTI, but is a more complex interface.

Start JDWP in QShell

To start JDWP and run the Java class SomeClass, enter the following command in QShell:

java -interpret -agentlib:jdwp=transport=dt_socket,
address=8000,server=y,suspend=n SomeClass

In this example, JDWP listens for connections from remote debuggers on TCP/IP port 8000, but you can use any port number you want; dt_socket is the name of the SRVPGM that handles the JDWP transport and does not change.

For additional options that you can use with -Xrunjdwp, see Sun VM Invocation Options by Sun Microsystems, Inc. These options are available for both JDK 1.4 and 1.5 on i5/OS.

Start JDWP from a CL command line

To start JDWP with the CL command, two new options have been added: AGTPGM and AGTOPTIONS.

The value of AGTPGM is JDWP and the value of AGTOPTIONS can be defined to be the same string that you would have used on the QShell command line.

JAVA CLASS(SomeClass) INTERPRET(*YES) AGTPGM(JDWP)
AGTOPTIONS('transport=dt_socket,address=8000,server=y,suspend=n') 

Using JVMDI/JVMTI is not recommended for Direct Execution code. You should run your application with the interpreter, or use the Just-In_Time (JIT) Compiler with full-speed debugging.

Java Debug Interface

Java Debug Interface (JDI) is a high-level Java language interface provided for tool development. JDI hides the complexity of JVMDI/JVMTI and JDWP behind some Java class definitions. JDI is included in the rt.jar file, so the front end of the debugger exists on any platform that has Java installed.

If you want to write debuggers for Java, you should use JDI because it is the simplest interface and your code is platform-independent.

For more information on JDPA, see Java Platform Debugger Architecture Overview by Sun Microsystems, Inc.