Debug Java applications remotely with Eclipse

JPDA introduction

---

IBM developerWorks : http://www.ibm.com/developerworks/library/os-eclipse-javadebug/index.html

---

Sun Microsystems’ Java Platform Debugger Architecture (JPDA) technology is a multitiered architecture that allows you to debug Java applications in all situations easily. The JPDA consists of two interfaces (the JVM Tool Interface and JDI, respectively), a protocol (Java Debug Wire Protocol), and two software components that tie them together (back-end and front-end). It’s designed for use by debuggers in any environment. JPDA is not only for desktop systems but works well with embedded systems, too.

The JVM Tool Interface (JVMTI) defines that a VM must provide for debugging. (Editor’s note: Starting with Java V5, JVMTI replaced JVMDI, which was used in Java V1.4.) The Java Debug Wire Protocol (JDWP) describes the format of debugging information and requests transferred between the process being debugged and a debugger front end, which implements the JDI, such as Eclipse, Borland JBuilder, and many others. The program being debugged is often called the debuggee in Sun’s JPDA specification. The JDI is a high-level interface to define the information and requests used for remote debugging. The architecture is structured as follows.
Listing 1. The Java Platform Debugger Architecture

         Components                      Debugger Interfaces

                 /    |--------------|
                /     |     VM       |
 debuggee -----(      |--------------|  <---- JVMTI - Java VM Tool Interface
                \     |   back-end   |
                 \    |--------------|
                 /           |
 comm channel --(            |  <------------ JDWP - Java Debug Wire Protocol
                 \           |
                 /    |--------------|
                /     |  front-end   |
 debugger -----(      |--------------|  <---- JDI - Java Debug Interface
                \     |      UI      |
                 \    |--------------|

Available connectors

In Sun’s reference implementation of JPDA, two transport mechanisms are provided on Microsoft® Windows®: socket transport and shared memory transport. Available connectors:
- Socket-attaching connector
- Shared-memory attaching connector
- Socket-listening connector
- Shared-memory listening connector
- Command-line launching connector

JDWP arguments

-Xdebug
Enables debugging features.

-Xrunjdwp:
Loads the implementation of JDWP in the target VM. It uses a transport and the JDWP protocol to communicate with a separate debugger application. Specific suboptions are described below.

Starting from Java V5, you can use the -agentlib:jdwp option, instead of -Xdebug and -Xrunjdwp. But if you have to connect to the VM prior to V5, -Xdebug and -Xrunjdwp will be the only choice. Following are brief descriptions of the -Xrunjdwp suboptions.

transport
Generally, socket transport is used. But shared-memory transport can also be used on the Windows platform, if available.

server
If the value is y, the target application listens for a debugger application to attach. Otherwise, it attaches to a debugger application at the specified address.

address
This is the transport address for the connection. If the server is n, attempt to attach to a debugger application at this address. Otherwise, listen for a connection at this port.

suspend
If the value is y, the target VM will be suspended until the debugger application connects.

For detailed explanations for each debug setting, refer to the JPDA documentation (see Resources).

Listing 2 shows an example of how to launch a VM in debug mode and listen for a socket connection at port 8765.
Listing 2. Target VM acts as a debug server

-Xdebug -Xrunjdwp:transport=dt_socket,server=y,address=8765

Listing 3 shows how to attach to a running debugger application using a socket on host 127.0.0.1 at port 8000.
Listing 3. Target VM acts as a debug client

-Xdebug -Xrunjdwp:transport=dt_socket,address=127.0.0.1:8000

Debug an application remotely

Details