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:
|
Related Reading 
Eclipse IDE Pocket Guide |
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.
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.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">
<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
|
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.
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
|
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.
|
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.
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.
Deepak Vohra is a NuBean consultant and a web developer.
Return to ONJava.com.
Copyright © 2009 O'Reilly Media, Inc.