I found this gem on IBM website when I looked for ways to debug my running applet. The original link:
http://www.ibm.com/developerworks/opensource/library/os-eclipse-javadebug/index.htmlRemote debugging can be useful for application development, such as developing a program for a low-end machine that cannot host the development platform, or debugging programs on dedicated machines like Web servers, whose services cannot be shut down. Other examples include Java applications running with limited memory or CPU power, such as mobile devices, or developers wanting to separate the application and development environments, etc.
If you don't have it already, download Eclipse V3.4 (Ganymede). In Ganymede, the socket listening connector has been added to the Remote Java Application launch-configuration type. Eclipse's new socket listening connector allows you to start the Java debugger, which listens for a connection on a specific socket. The program being debugged can then be started with command-line options to connect to the debugger. Prior to the Ganymede release, only a socket-attaching connector was provided, and the program being debugged had to be a debug host that was connected by the debugger. It is impractical for mobile devices to be a host due to insufficient memory and CPU power.
To use remote debugging, Java Virtual Machine (JVM) V5.0 or later must be used, such as IBM® J9 or Sun Microsystems' Java SE Development Kit (JDK). In this article, we focus on remote debugging, rather than detail each of Eclipse's debugging features. See
Resources for more information about debugging with Eclipse and where to find the aforementioned software.
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 ArchitectureComponents 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 |
\ |--------------|
|
Therefore, any third-party tools and VM based on JPDA should work together without complaint. This client-server architecture allows you to debug a Java program from a local workstation running the platform, or even debug it from a remote computer on your network.
Before talking about the debug-scenario stuff, we need to introduce two terms used in the JPDA specification: connector and transport. A connector is a JDI abstraction used to establish a connection between a debugger application and a target VM. A transport defines how applications access and transmit data between the front end and back end. The connectors "map" to the available transport types and the modes of connection. 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
In establishing a connection between a debugger application and target VM, one side acts as a server and listens for a connection. At some later time, the other side attaches to the listener and establishes a connection. The connections allow the debugger application or the target VM to act as a server. The communications among processes can be running on one machine or different machines.
The problem with debugging a Java program remotely is not in the debugger front end but the remote Java back end. Unfortunately, there is not much information about this in the Eclipse help system. In fact, JDI and JVMTI are implemented by Eclipse and the Java runtime environment, respectively. The only thing we are concerned with is the JDWP, which contains the information to communicate with the JVMTI and JDI. The JDWP contains many arguments that have been added to invoke the application for the remote Java application. Following are some of the arguments used in this article.
- -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
|
Eclipse is a graphical Java debugger front end. The JDI is implemented in org.eclipse.jdt.debug bundle. In this article, we don't discuss the details of JDI implementation. See
Resources for information about Eclipse JDT and Java JDI technology.
The first thing we want to know is which Eclipse connector to use. To learn the remote connection types provided by Eclipse, you can add a launch configuration in Remote Java Application by going to the Eclipse menu and selecting Run > Debug Configurations..., then selecting the connector from the dropdown list. Two connectors are provided in Ganymede:
- Socket Attach
- Socket Listen
For the socket-listening connector, the Eclipse VM will be the host to be connected by the remote Java application. For the socket-attaching connector, the target VM will be the host. There is no difference for application debugging between the two connectors — the user may choose. A good rule of thumb is to use the faster, more powerful computer as the VM debug host because of the computational resources required.
Before debugging your Java application, you may need to make sure the debug options are all enabled for your remote application. If that information is not available, you will get an error message, such as "Debug information is not available" or "Unable to install breakpoint due to missing line number." You can modify the settings from the Eclipse menu by changing what's set in Window > Preferences > Java > Compiler.
Figure 1. Debug options in EclipseWe are ready to start debugging an application remotely. Let's do it step by step:
- 1. Create a Java project with a simple class
- We create a simple class for debugging purpose. Listing 4 shows the sample code.
Listing 4. Sample code for debuggingpackage com.ibm.developerWorks.debugtest;
public class test {
public static void main(String[] args) {
System.out.println("This is a test.");
}
}
|
- 2. Set a breakpoint
- Set a breakpoint in the code. In this example, we set the breakpoint in the line
System.out.println("This is a test.");.
Figure 2. Set breakpoints in Eclipse3. Debug the application locallyBefore debugging your application, ensure that the debug options described in Figure 1 are enabled for the project. It's unnecessary to debug an application locally, but we can make sure all the debug information is available. Right-click on the Java project, select Debug As and select Java Application (see Figure 3). If the application execution is stopped at the breakpoint, the debugging information is presented correctly. You can continue to use the debugging features, such as displaying the debug stack, variables, or breakpoint management, etc. Figure 3. Debug the application locally
4. Export the Java projectWe will use this application as the debug target. Right-click on the Java project, select Export, select Java, then chooseJAR file or Runnable JAR file to export the project. The JAR file will be generated at the desired location. Be aware that if the Java source does not match the target application, the debug function will not work correctly.- 5. Run the Java application manually
- Open a console to launch the application manually to make sure the Java runtime environment is configured properly.
Listing 5. Sample to invoke Java application - 6. Debug the application remotely
- Copy the JAR file to the appropriate location on the remote computer, or even the same machine, invoke the debug server, and then attach a client to it. The simple Java application can act as a debug server or client. Depending on the configuration, you can choose either Socket Attach or Socket Listen connection type in Eclipse. Learn how to run the application as a server or client in the following two sections.
The following example invokes the Java application on the remote side, acts as a debug server, and listens for a socket connection on port 8000. The target VM will be suspended until the debugger connects.
Listing 6. VM invocation sample for socket attaching mode in Eclipse
java -Xdebug -Xrunjdwp:transport=dt_socket,server=y,address="8000" -jar
test.jar
|
Start Eclipse using the remote launch configuration and specify the target VM address of the remote application. To do this, clickRun > Debug Configurations, and double-click the Remote Java Application in the Eclipse menu. From the newly created launch configuration, specify the IP and port for target application. To run the remote application in the same machine, simply specify the host IP as localhost or 127.0.0.1.
Figure 4. Configuration of socket-attaching connection
Select Allow termination of remote VM option to terminate the VM to which you are connecting during application debugging.
Figure 5. Terminate button in Eclipse
The second example is to use a simple Java application that acts as a debug client, and the debugger front end acts as a debug server. Eclipse uses the socket listen-mode connection type for listening. The debug front end must be started in advance to listen on a specific port. Figure 6 shows a sample configuration to set up listening.
Figure 6. Configuration of socket-listening connection
Click the Eclipse Debug button, and the status bar will show the message "waiting for vm to connect at port 8000..." When you see that, start the remote application. Listing 7 shows how to invoke the Java application as a debug client and attach it to a running debugger application using a socket on host 127.0.0.1 at port 8000.
Listing 7. VM invocation sample for socket-listening connection in Eclipse
java -Xdebug -Xrunjdwp:transport=dt_socket,address=127.0.0.1:8000,suspend=y
-jar test.jar
|
If everything goes well, the debug perspective will be displayed to support the application debugging, and the execution of the remote Java application will be stopped normally. This is similar to Step 3 that we did in local debugging (see Figure 3). At this point, you can use standard debugging functions, such as setting breakpoints and values, step execution, etc.
This article illustrated how to use the Eclipse built-in remote Java application configuration type to perform application debugging remotely. It introduced how to set up a Java application to invoke remote debugging and helped you understand the connectors Eclipse provides. Finally, you learned how to apply this technology to your projects.
