Configuring Eclipse for Remote Debugging

byDeepak 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 byEclipse, 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 likeJBoss 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:
Start the JBoss server. Connect the Eclipse remote debugger to the JBoss server. Debug in the Eclipse GUI.
Related Reading
Eclipse IDE Pocket Guide
ByEd 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
Download thejboss-4.0.2.zip file. Install the JBoss 4.02 application server by extracting the .zip file to an installation directory. Download the Eclipse 3.0 or Eclipse 3.02 .zip fileeclipse-SDK-3.0-win32.zip. 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:
xmlns="http://java.sun.com/xml/ns/j2ee" version="2.4"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"> JBossServlet JBossServlet servlets.JBossServlet JBossServlet /catalog
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:
destdir="${src}/WEB-INF/classes">
The build.xml file has the properties listed in the following table.
PropertyDescription
buildThe build directory used to build the web application.
srcThe src directory has the source files for the web application.
jboss.deployThe JBoss directory in which the web application is deployed.
distThe directory in which the web application .war file is generated.
j2sdkeeThe J2sdkee directory.
build.xml also has the following targets:
TargetDescription
initThe initialization target; the target to create the web application directories.
compileThe target to compile the web application.
webappThe 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 theJava 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:
ParameterDescription
-XDebugEnables debugging
-XnoagentDisables previous debugging agent.
-XrunjdwpSpecifies the connection mechanism, the transport address, and server and suspend values.
For further explanation of the debug settings, refer to theJPDA 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.
Eclipse IDEJBoss serverJava Platform for Debugger Architecture
Deepak Vohra is a NuBean consultant and a web developer.
Copyright ?2005 O‘Reilly Media, Inc.
_xyz