There are three steps to getting started with debugging the registry/repository:
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.
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.
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
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
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.
This starts Tomcat with the CATALINA_OPTS environment variable set to the value necessary for debugging Tomcat.
This starts Tomcat with the JPDA_TRANSPORT and JPDA_ADDRESS environment variables set to the value necessary for debugging Tomcat.
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.
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.
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
Most Java debuggers and IDEs provide a way to attach to a running program to debug it.
Attaching to the running program is very simple with the jdb Java debugger:
jdb -attach <address> -sourcepath <directories separated by ":">
Where:
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.