Debugging

There are three steps to getting started with debugging the registry/repository:

  • Compiling with debugging enabled
  • Running the client or server or both with debugging enabled
  • Attaching to the running program to debug it

Compiling With Debugging Enabled

Make sure that the value of the compile.debug property is true in your build.xml or in your build.properties file, if it is defined in that file.

Running With Debugging Enabled

Running The Server With Debugging Enabled

Since the registry server operates as one or more servlets in servlet container, it is simpler to attach a JPDA-enabled debugger to the running servlet container that has debugging enabled than to try to run the servlet container in a debugger.

The specifics of starting a servlet container with debugging enabled varies with the container, and there may be more than one way to do it for a particular servlet container. This document describes two ways of starting Tomcat with debugging enabled, but if you use a different method or a different servlet container, please provide the information so we can add it here.

Running a servlet container with debugging enabled slows it down considerably, so it's best to do this only when you're actually going to debug the program.

Commands for Running Tomcat with Debugging Enabled

Using catalina jpda start

Tomcat has built-in support for debugging with a JPDA enabled debugger. To use it, start Tomcat with the catalina.sh script (on Unix) or catalina.bat script (on Windows) with ant extra jpda argument. Tomcat then runs with default values for the JPDA settings for how the debugger can connect to Tomcat. To be sure of the settings, you can set the JPDA_TRANSPORT and JPDA_ADDRESS environment variables before starting Tomcat:

bash:

declare -x JPDA_TRANSPORT=dt_socket
declare -x JPDA_ADDRESS=8000
$JWSDP_HOME/bin/catalina.sh jpda start

csh:

setenv JPDA_TRANSPORT dt_socket
setenv JPDA_ADDRESS 8000
$JWSDP_HOME/bin/catalina.sh jpda start

Windows:

set JPDA_TRANSPORT=dt_socket
set JPDA_ADDRESS=8000
%JWSDP_HOME%\bin\catalina jpda start
Using catalina start and CATALINA_OPTS

Alternatively, you can set the java program's command-line arguments for the JPDA settings. For Tomcat, you specify them in the CATALINA_OPTS environment variable and the catalina.sh or catalina.bat script adds the value of the environment variable to the java command that starts Tomcat; for example:

bash:

declare -x CATALINA_OPTS="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=8000"
$JWSDP_HOME/bin/catalina.sh start

csh:

setenv CATALINA_OPTS "-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=8000"
$JWSDP_HOME/bin/catalina.sh start

Windows:

set JPDA_TRANSPORT=-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=8000
%JWSDP_HOME%\bin\catalina start

Ant Targets for Running Tomcat with Debugging Enabled

The server.debugSocket Ant property sets the port number to use when connecting to Tomcat after it has been started with one of these targets. You can set the property in your build.properties, and that will override the default set in build.xml.

debug.tomcat Ant Target

This starts Tomcat with the CATALINA_OPTS environment variable set to the value necessary for debugging Tomcat.

jpda.tomcat Ant Target

This starts Tomcat with the JPDA_TRANSPORT and JPDA_ADDRESS environment variables set to the value necessary for debugging Tomcat.

Running The Registry Browser Java UI With Debugging Enabled

You can start the Registry Browser Java UI with debugging enabled using the debug.browser Ant target

The client.debugSocket Ant property specifies the port to which to attach to debug the browser. You can set the property in your build.properties, and that will override the default set in build.xml.

Running a Unit Test With Debugging Enabled

You can start a single unit test with debugging enabled using the debug.single Ant target; for example:

ant -Dtest=org.freebxml.omar.client.xml.registry.I18NTest debug.single

The test.debugSocket Ant property specifies the port to which to attach to debug the browser. You can set the property in your build.properties, and that will override the default set in build.xml.

Running The Admin Tool With Debugging Enabled

You can start the Admin Tool with debugging enabled using the debug.adminTool Ant target; for example:

ant -DadminTool.args="-command ls" debug.adminTool

The client.debugSocket Ant property specifies the port to which to attach to debug the browser. You can set the property in your build.properties, and that will override the default set in build.xml.

If you want to debug the Admin Tool while using it interactively, you'll have to provide the appropriate command-line arguments when you start the Admin Tool; for example:

java -Xdebug -Xrunjdwp:transport=dt_socket,address=1044,server=y,suspend=y -jar build/lib/admin-tool.jar

Attaching to the Running Program to Debug It

Most Java debuggers and IDEs provide a way to attach to a running program to debug it.

jdb Java Debugger

Attaching to the running program is very simple with the jdb Java debugger:

jdb -attach <address> -sourcepath <directories separated by ":">

Where:

<address>
Address specified when starting the program

NetBeans IDE

Debugging the running program using NetBeans is almost as simple, but you first need to do some setting up so that NetBeans knows where to find your source code that you are debugging. See the Using NetBeans page for how to set up NetBeans and how to attach the NetBeans debugger to a running program.