Debugging FAQs

How do I debug Cocoon using JDK1.3+?

With JDK1.3 or above, first set the CATALINA_OPTS (for Tomcat 4.x as shown below (on Win2K).

set CATALINA_OPTS=-server -Xdebug -Xnoagent -Djava.compiler=NONE
    -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=8000

Note

For Tomcat 3.x the param is TOMCAT_OPTS and the first value is -classic instead of -server.

Add it to the catalina.bat, that can be found in %TOMCAT_HOME%\bin\, right after the first rem section.
The same information in more detail can be found at Setting up Tomcat for Remote Debugging.

The problem of this approach is the blocking of using Tomcat in another mode. You always have to touch catalina.bat again when changing the mode and this file is really a batch beast, isn't it? Furthermore catalina.bat is only a starting mode library and should not be touched by hand IMO.
Let me propose my approach: Go to the last line of startup.bat where catalina.bat is called. Replace

call "%EXECUTABLE%" start %CMD_LINE_ARGS%

with

set JPDA_TRANSPORT=dt_socket
set JPDA_ADDRESS=8000
call "%EXECUTABLE%" jpda start %CMD_LINE_ARGS%

A switch can now be done by adding and removing jpda. You can also place the old line in comments and switch between them. Or you copy startup.bat to debug.bat and do the changes there.

Note

Note that Tomcat must be started using startup.bat in order to set these values; if you are using "java.exe -jar ...bootstrap.jar start" or anything similar to start Tomcat, you have to set the CATALINA_OPTS on the commandline or for Windows in general.

Note

If you use Jetty included with Cocoon 2.1 it's much easier. Instead of doing "cocoon.bat servlet" you simply call "cocoon.bat servlet-debug".

After having started Tomcat or the servlet container of your choice in remote debugging mode, attach the debugger to localhost:8000 using "jdb -attach myhost:8000". If you get an error "Error accessing shared memory, rc = -1", try "jdb -connect com.sun.jdi.SocketAttach:port=8000" instead.
More information on this can be found in the JPDA documentation.

Note

The attaching of the debugger to that port can be done very easily in almost all modern IDEs as Eclipse, IDEA, NetBeans or JBuilder. Mostly port 8000 and dt_socket are preselected.

Now that I have prepared Tomcat and my IDE for debugging: How do I debug?

Of course we can not give to many details here as it might be different for all the possible IDEs out there, but the general proceeding should be the same. The following steps are for jdb, it should be much easier for the IDEs.
1. Set a breakpoint in a class via "stop in org.apache.cocoon.components.pipeline.AbstractProcessingPipeline.checkPipeline".
2. Enter a URL in your browser to get Cocoon to do the stuff that needs debugging. When your breakpoint is hit, you'll get the message in jdb:
Breakpoint hit: "thread=Thread-11", org.apache.cocoon.components.pipeline.AbstractProcessingPipeline.checkPipeline(), line=363 bci=0.
3. Use the debugger commands "print", "next", and "cont" to examine the data and step through the code.

Errors and Improvements? If you see any errors or potential improvements in this document please help us: View, Edit or comment on the latest development version (registration required).