zz~ Debug Java applications remotely with Eclipse

Debug Java applications remotely with Eclipse

Use the power of the Eclipse IDE to spread around your Java application debugging

Charles Lu ( charleslu@tw.ibm.com ), Software Engineer, IBM

Charles Lu is a software developer at the IBM China Software Development Lab and currently works on IBM Lotus Expeditor development. He is interested in device programming, instant messaging, and voice technology.

Summary:   You don't need to debug Java™ applications on just your local desktop. Learn how to spread around your debugging using different connection types that make up remote debugging. This article explains the features and examples that show how to set up remote application debugging.

Tags for this article:   debug , eclipse , java

Tag this!

Update My dW interests ( Log in | What's this? ) Skip to help for Update My dW interests

Date:   09 Dec 2008
Level:  Intermediate
Also available in:   Russian  Japanese

Activity:   47354 views
Comments:   1 (View  | Add comment - Sign in)

Average rating (24 votes)
Rate this article

Remote 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.

Prerequisites

Launch-configuration type

A launch configuration keeps a set of attributes that can be used to launch a program. The launch-configuration type is a unique type of program that can be launched in the Eclipse platform.

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.

JPDA introduction

Frequently used acronyms

• JDI — Java Debug Interface
• JDT — Java Development Tools
• JDWP — Java Debug Wire Protocol
• JPDA — Java Platform Debugger Architecture
• JVM — Java Virtual Machine
• JVMDI — JVM Debug Interface
• JVMTI — JVM Tool Interface
• VM — Virtual Machine

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 | / |--------------|

 

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:<sub-options>

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

 

---

Back to top

Remote debugging features in Eclipse

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 Eclipse

---

Back to top

Debug an application remotely

We 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 debugging

package 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 Eclipse

3. Debug the application locally

Before 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 project

We will use this application as the debug target. Right-click on the Java project, select Export , select Java , then choose JAR 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

java -jar test.jar

 

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.

Target VM acts as debug server

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, click Run > 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

Target VM acts as debug client

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.

---

Back to top

Conclusion

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.

 

Resources

Learn

• "Eclipse Ganymede at a glance " is an overview of several Ganymede projects, along with resources for more information.
  
• For an introduction to the debugging with the Eclipse platform, see "Debugging with the Eclipse Platform ."
  
• Expand your Eclipse debugging knowledge by checking out Eclipse Debugging Resources .
  
• Learn more about Java Platform Debugger Architecture by Sun Microsystems.
  
• Read the Java Platform Debugger Architecture documentation to learn more about JPDA.
  
• Read the Java Debug Interface documentation to learn more about JDI.
  
• The JDT project provides the tool plug-ins that implement a Java IDE supporting the development of any Java application, including Eclipse plug-ins.
  
• Check out the "Recommended Eclipse reading list ."
  
• Browse all the Eclipse content on developerWorks.
  
• New to Eclipse? Read the developerWorks article "Get started with Eclipse Platform " to learn its origin and architecture, and how to extend Eclipse with plug-ins.
  
• Expand your Eclipse skills by checking out IBM developerWorks' Eclipse project resources .
  
• To listen to interesting interviews and discussions for software developers, check out check out developerWorks podcasts .
  
• Stay current with developerWorks' Technical events and webcasts .
  
• Watch and learn about IBM and open source technologies and product functions with the no-cost developerWorks On demand demos .
  
• Check out upcoming conferences, trade shows, webcasts, and other Events around the world that are of interest to IBM open source developers.
  
• Visit the developerWorks Open source zone for extensive how-to information, tools, and project updates to help you develop with open source technologies and use them with IBM's products.
  

Get products and technologies

• The Java 2 Standard Edition V5 or greater is available from Sun Microsystems .
  
• Check out the latest Eclipse technology downloads at IBM alphaWorks .
  
• Download Eclipse Platform and other projects from the Eclipse Foundation.
  
• Download IBM product evaluation versions , and get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®.
  
• Innovate your next open source development project with IBM trial software , available for download or on DVD.
  

Discuss

• The Eclipse Platform newsgroups should be your first stop to discuss questions regarding Eclipse. (Selecting this will launch your default Usenet news reader application and open eclipse.platform.)
  
• The Eclipse newsgroups has many resources for people interested in using and extending Eclipse.
  
• Participate in developerWorks blogs and get involved in the developerWorks community.