Download the Eclipse workspace
Download the jar file

Introduction

This is a study note on debugging a remotely running Java application from Eclipse.

Background

It is not always required, but it may sometimes become necessary to debug a remotely running Java application from your IDE. Fortunately remote debugging support is provided by the JVM, and most IDEs has the ability to debug a remotely running application. In this study note, I will show you an example on debugging a remotely running application from Eclipse. The test on this example has been conducted on the following platforms:

JDK - jdk1.7.0_60;
Eclipse - Eclipse IDE for Java EE Developers, version: Kepler Service Release 2;
Operating System - Windows 7.

The same JDK (jdk1.7.0_60) is used to run both the Eclipse and the example Java application. If you are new to Eclipse and Java programming, you can take a look at my earlier post "Set Up Eclipse for Java Development".

The Example Swing Application

To test the remote debugging feature on Eclipse, a small Swing application is created in Eclipse, which is shown in the package explorer.

This small Swing application is implemented in the "SwingApplication.java" file.

package com.song.simpleapp;
    
import java.awt.Font;
import java.awt.event.ActionEvent;
import java.awt.event.ActionListener;
    
import javax.swing.JButton;
import javax.swing.JFrame;
import javax.swing.JOptionPane;
    
public class SwingApplication extends JFrame {
    private static final long serialVersionUID = 1L;
    
    SwingApplication() {
        setSize(800, 500);
        setTitle("A Simple Swing Application - Remote Debuging Test");
        setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
        
        JButton btn = new JButton("Click on me");
        btn.setFont(new Font(Font.SERIF, Font.BOLD, 16));
        btn.addActionListener(new ActionListener() {
            public void actionPerformed(ActionEvent e) {
                String remote = "Remote";
                String debuging = "Debuging";
                String test = "Test";
                
                String message = remote + " " + debuging + " " + test
                        + " is going on!";
                JOptionPane.showMessageDialog(null, message);
            }
        });
        
        add(btn);
        setVisible(true);
    }
    
    public static void main(String[] args) {
        new SwingApplication();
    }
    
}

This is a very simple Swing application. In this application, a JButton is added to the JFrame. Clicking on the button will pop up a message dialog box.

Export a Jar File for the Application

To run the application independently (remotely) from the Eclipse, we can export a Jar file. In Eclipse, we can right click on the project -> Export to open the exporting utility.

Since we are exporting a jar file, we can select it from the Java section and click the "Next" button.

Since we do not need the ".classpath" and ".project" files in the jar file, we can uncheck the checkboxes next to them. We can then select a location and give a name for the jar file. If we click the "Finish" button, the jar file will be generated at the desired location.

Run the Example Application with "-Xdebug"

In order to remotely debug the application, we will need to add two additional parameters when we launch it.

"-Xdebug" - This option enables the debugging capabilities in the JVM;
"-Xrunjdwp" - This option tells the JVM how the remote debugging should be configured.

If you want to take a detailed look at these option parameters, you can check out this link and this link. Make sure the correct JRE is in the environment path, we can launch the Swing application using the following command from the directory where the jar file is located.

java -Xdebug -Xrunjdwp:server=y,transport=dt_socket,address=4000,suspend=n -cp ASimpleSwingApplication.jar com.song.simpleapp.SwingApplication

When I export the jar file, I named it as "ASimpleSwingApplication.jar". If you want to repeat this experiment yourself and if you give a different name to the jar file, you will need to specify the correct file name when you launch the application. Upon the successful launch, we will see the following application running.

According to the Oracle documentation, the "-Xdebug" option should never be used in the production environment unless you want to debug the application, The application will not be running at the full speed if the "-Xdebug" option is used.

Remote Debug the Running Application From Eclipse

To remotely debug the running application, the Eclipse will need the source code of the application. If you have already closed Eclipse, you can re-start it and load the workspace into it. We can then right click on the project -> Debug as -> "Debug configurations ..." to open the debug configuration utility.

Since we are going to remotely debug the application, we will need to select "Remote java Application" from the left side of the window.

make sure the correct project which has the Java source code is selected;
In the connection properties, we will need to set the host as "localhost" because the application is running on the same computer as the Eclipse;
Will need to specify the port as "4000" because we specified "address=4000" when we start the Swing application.

We can then click the "Debug" button to debug the application. If we set a breakpoint in the "actionPerformed" method and click the "Click on me" button in the running application, we will see that the break point is hit in the Eclipse.

We can then step through the code and enjoy all the debugging capabilities and good features from the Eclipse as if the application is started from the Eclipse itself.

Points of Interest

This is a study note on debugging a remotely running Java application from Eclipse.
I only experimented the steps on my computer with the specified JDK and Eclipse versions. If you want to try it yourself and if your environment is different, you may encounter some problems. But the general idea should work the same way after you resolve the issues.
The remote debugging is not only available to stand-alone applications, it is available to all the Java applications, including web applications hosted in Tomcat and other application servers.
I hope you like my postings and I hope this article can help you one way or the other.

History

First revision - 7/10/2014.

Remote Debug Java Applications From Eclipse