Configuring Eclipse for Remote Debugging

Configuring Eclipse for Remote Debugging

by Deepak Vohra
08/31/2005

If a J2EE developer has deployed an application in an application server and wants to debug the application from the Eclipse IDE, the Eclipse IDE provides a remote debugger to connect to the application server and debug the application. Without a debugger, the error message has to be obtained from the application server‘s error logs.

With the remote debugger provided by Eclipse, breakpoints may be added to the application file, allowing you to debug the application in Eclipse. When an application is run in an application server like JBoss and the application generates an error, the application gets suspended and the Eclipse IDE Debug perspective displays the line that has generated the error. In this tutorial, we shall debug a JBoss application server application in Eclipse.

To debug, we will do the following:

1. Start the JBoss server.
2. Connect the Eclipse remote debugger to the JBoss server.
3. Debug in the Eclipse GUI.

Related Reading Eclipse IDE Pocket Guide By Ed Burnette Table of Contents Index Sample Chapter

We shall develop an example servlet application and deploy the application in JBoss. First, the servlet is run without any error; subsequently, an error is introduced into the servlet to demonstrate the remote debugging feature in Eclipse.

Preliminary Setup

1. Download the jboss-4.0.2.zip file.
2. Install the JBoss 4.02 application server by extracting the .zip file to an installation directory.
3. Download the Eclipse 3.0 or Eclipse 3.02 .zip file eclipse-SDK-3.0-win32.zip.
4. Install the Eclipse 3/3.02 IDE.

Developing a JBoss Application in Eclipse

After installing the JBoss server and the Eclipse IDE, develop a servlet application to run and debug in the JBoss server. The example servlet application consists of a doGet method that prints out a String message to the browser. The example servlet, JBossServlet.java, is listed below:

package servlets;
import java.io.*;
import javax.servlet.*;
import javax.servlet.http.*;

public class JBossServlet extends HttpServlet {
  public void doGet(HttpServletRequest request,
                    HttpServletResponse response)
      throws ServletException, IOException {
    PrintWriter out = response.getWriter();
    out.println("Eclipse Remote Debugging");
  }
}

Create a directory structure for a web application. Create a WEB-INF directory and a classes directory in the WEB-INF directory. Create a package directory, servlets, for the example servlet, and copy the JBossServlet.java file to the servlets directory. Create a web.xml deployment descriptor for the web application. Copy the web.xml file to the WEB-INF directory. The web.xml is as follows:

<?xml version="1.0" encoding="UTF-8"?>

<web-app

xmlns="http://java./xml/ns/j2ee" version="2.4" 

xmlns:xsi="http://www./2001/XMLSchema-instance" 

xsi:schemaLocation="http://java./xml/ns/j2ee 

http://java./xml/ns/j2ee/web-app_2_4.xsd">

 <servlet>

    <display-name>JBossServlet</display-name>
    <servlet-name>JBossServlet</servlet-name>
    <servlet-class>servlets.JBossServlet</servlet-class>

 </servlet>
 <servlet-mapping>
     <servlet-name>JBossServlet</servlet-name>
     <url-pattern>/catalog</url-pattern>
 </servlet-mapping>
 

 </web-app>

The example servlet is mapped to the URL pattern /catalog. The structure of the web application is illustrated below.

     /WEB-INF
      |      |
   web.xml classes
                 |
                 servlets
                      |
                     JBossServlet.class

Building and Deploying with Ant

The compiling, packaging, and deploying of the web application is done in the Eclipse IDE with an Ant build.xml file. Develop an Ant build.xml file that consists of targets to compile the JBossServlet.java file and package and deploy the webapp.war web application. The build.xml file is listed below:

<project name="jbossApp" default="webapp" basedir="."> 
<property name="build" value="build"/>
<property name="src" value="." /> 
<property name="jboss.deploy"
 value="C:\JBoss\jboss-4.0.2\server\default\deploy"/>
<property name="dist" value="dist"/>
<property name="j2sdkee" value="C:\J2sdkee1.4"/>
<target name="init">
    <tstamp/>
  <mkdir dir="${build}" />
  <mkdir dir="${dist}" />
  <mkdir dir="${build}/WEB-INF" /> 
  <mkdir dir="${build}/WEB-INF/classes" />
</target>
<target name="compile" depends="init">
  <javac debug="true" classpath="${j2sdkee}/lib/j2ee.jar" 
  srcdir="${src}/WEB-INF/classes" 

  destdir="${src}/WEB-INF/classes"> 
    <include name="**/*.java" /> 
  </javac> 
  <copy todir="${build}/WEB-INF"> 
    <fileset dir="WEB-INF" >
      <include name="web.xml" />
    </fileset> 
  </copy> 
 <copy todir="${build}/WEB-INF/classes"> 
    <fileset dir="${src}/WEB-INF/classes" >
      <include name="**/JBossServlet.class" />
    </fileset> 
  </copy> 
</target>
<target name="webapp" depends="compile">
 <war basedir="${build}" includes="**/*.class"
 destfile="${dist}/webapp.war"  webxml="WEB-INF/web.xml"/> 
 <copy file="${dist}/webapp.war" todir="${jboss.deploy}"/>
  </target>
</project>

The build.xml file has the properties listed in the following table.

Property	Description
build	The build directory used to build the web application.
src	The src directory has the source files for the web application.
jboss.deploy	The JBoss directory in which the web application is deployed.
dist	The directory in which the web application .war file is generated.
j2sdkee	The J2sdkee directory.

build.xml also has the following targets:

Target	Description
init	The initialization target; the target to create the web application directories.
compile	The target to compile the web application.
webapp	The target to generate the .war file.

The debug attribute of the javac task in the build target is set to true to enable compilation in debug mode. By compiling an application in debug mode, the line number that generates the exception in a JBoss server application gets displayed in Eclipse‘s Debug perspective.

Back to Eclipse

Create a new project in the Eclipse IDE. Select File -> New -> Project, as shown in Figure 1.

Figure 1. New project

This displays the New Project frame. In the New Project wizard, select Java -> Java Project. Click the Next button: this brings up the New Java Project frame. In the New Java Project frame, specify a project name--EclipseJBoss, for example--and click the Next button, as shown in Figure 2.

Figure 2. Creating a Java project

In the Java Settings frame, add a source folder to the project with the Add Folder button, as illustrated in Figure 3.

Figure 3. Adding a source folder

This brings up the New Source Folder frame. Use this to specify a folder name; src, for example. This adds a source folder to the project. A message prompt gets displayed, asking you to update the source folder and the output folder. In the New Java Project frame, click the Finish button to create the project, as shown in Figure 4.

Figure 4. Java build settings

A new project gets added to the Eclipse IDE, as shown in Figure 5.

Figure 5. Eclipse JBoss project

Next, select File -> Import to import the example servlet source folder to the project. The project‘s src folder and build.xml file need to be imported if the src folder and build.xml file were not created in the Eclipse IDE. In the Import Select frame, select File System and click the Next button. In the Import File System frame, select the src folder and the build.xml file, and click the Finish button, as shown in Figure 6.

Figure 6. Importing file system

This adds the servlet source files to the project, as shown in Figure 7.

Figure 7. Servlet source files

Run the build.xml file to compile, package, and deploy the servlet web application to the JBoss server. Right-click the build.xml file and select Run -> Ant Build, as shown in Figure 8.

Figure 8. Running the Ant build file

Ant generates the web application .war file webapp.war and deploys it to the JBoss application server‘s deploy directory. The output from Ant is shown in Figure 9.

Figure 9. Output from Ant

Next, start the JBoss server with the bin/run script. Invoke the example servlet in a web browser with the URL http://localhost:8080/webapp/catalog. The JBossServlet runs in the JBoss server and the output gets displayed in the browser, as shown in Figure 10.

Figure 10. JBossServlet in JBoss server

Configuring a Remote Debugging Configuration in Eclipse

To remotely debug a JBoss application in Eclipse, start the JBoss server in debug mode. Set the JBoss server to debug mode by setting the debug options in the bin/run batch script file. The debugging provided by JBoss is based on the Java Platform Debugger Architecture (JPDA). Set the JAVA_OPTS variable as follows:

set JAVA_OPTS= -Xdebug -Xnoagent 
  -Xrunjdwp:transport=dt_socket,address=8787,
  server=y, suspend=n %JAVA_OPTS%

The different debug parameters are:

Parameter	Description
-XDebug	Enables debugging
-Xnoagent	Disables previous debugging agent.
-Xrunjdwp	Specifies the connection mechanism, the transport address, and server and suspend values.

For further explanation of the debug settings, refer to the JPDA documentation.

To demonstrate the remote debugging feature of Eclipse, we need to throw an exception in JBossServlet. As an example, add a NullPointerException to JBossServlet.java by replacing:

out.println("Eclipse JBoss  Debugging");

with

String str=null;

out.println(str.toString());

Next, configure a debug configuration for the Eclipse project. Select the Debug option in the Debug Option List, as shown in Figure 11.

Figure 11. Debug

This displays the Debug frame. In the Debug frame, select the Remote Java Application node. Right-click the node and select New, as shown in Figure 12.

Figure 12. New debug configuration

In the Debug Configuration frame, specify a name for the debug configuration. Select the project that is to be debugged, namely the EclipseJBoss project previously created in the Eclipse IDE. Select the default value for Connection Type. In the Connection Properties, specify localhost as the Host and specify the Port as the port that was specified in the run batch script of the JBoss server, 8787. Click on the Apply button to add the remote Java application debug configuration, as shown in Figure 13.

Figure 13. JBoss debug configuration

Next, add exception breakpoints to the JBossServlet.java file. Earlier, we added a NullPointerException to JBossServlet. To add a breakpoint to the servlet class, select Run -> Add Java Exception Breakpoint, as shown in Figure 14.

Figure 14. Adding Java exception breakpoint

In the Add Java Exception Breakpoint frame, select the NullPointerException, as shown in Figure 15. The NullPointerException breakpoint gets added to the servlet class.

Figure 15. NullPointerException breakpoint

If a NullPointerException is generated in the servlet application in the JBoss server, the application gets suspended and the Debug perspective of the Eclipse IDE displays the exception.

Remote Debugging a JBoss Application

Having configured a debug configuration for the example servlet application deployed in the JBoss server, we shall debug the servlet application in the Eclipse IDE. Create a webapp.war web application from the modified (with the NullPointerException) JBossServlet.class file with the build.xml file, as explained in the "Developing a JBoss Application in Eclipse" section. Start the JBoss server. With the debug options specified in the run batch file, the server starts in debug mode.

Next, select the EclipseDebug debug configuration in the Debug frame. Click on the Debug button to connect the remote debugger to the JBoss server, as shown in Figure 16.

Figure 16. Connecting the remote debugger to the JBoss server

This connects the Eclipse remote debugger to the JBoss server. Select the Debug Perspective button to display Eclipse‘s debug perspective. In the Debug perspective, the remote debugger is shown connected to the JBoss server at localhost, port 8787, as shown in Figure 17.

Figure 17. Remote debugger connected to the JBoss server

Access the JBossServlet in the JBoss server with the URL http://localhost:8080/webapp/catalog in a browser. Because the servlet throws a NullPointerException, the servlet gets suspended with a NullPointerException, as indicated in the Debug perspective. The line that produced the exception gets displayed, as shown in Figure 18.

Figure 18. JBoss server suspended at NullPointerException

The line that throws the exception is out.println(str.toString());. The servlet application may be debugged with the different debug options listed by selecting Run in the Eclipse IDE.

Conclusion

We remotely debugged an application deployed to the JBoss server in the Eclipse IDE. An application deployed in another application server such as WebLogic may also be debugged by configuring that server to start in debug mode.

Resources

• Eclipse IDE
• JBoss server
• Java Platform for Debugger Architecture

Deepak Vohra is a NuBean consultant and a web developer.

---

Copyright ?2005 O‘Reilly Media, Inc.