apache > cocoon

- Home

# 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).