joerg 2004/01/06 19:14:10
Modified: src/documentation/xdocs/faq faq-debugging.xml Log: extended documentation on debugging (with support of Lars Huttar, lars(at)huttar.net) Revision Changes Path 1.2 +102 -25 cocoon-2.1/src/documentation/xdocs/faq/faq-debugging.xml Index: faq-debugging.xml =================================================================== RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/faq/faq-debugging.xml,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- faq-debugging.xml 9 Mar 2003 00:07:55 -0000 1.1 +++ faq-debugging.xml 7 Jan 2004 03:14:10 -0000 1.2 @@ -1,31 +1,108 @@ <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE faqs PUBLIC "-//APACHE//DTD FAQ V1.0//EN" "../dtd/faq-v10.dtd"> - <faqs title="Debugging FAQs"> -<faq> - <question> - How do I debug Cocoon using JDK1.3+? - </question> - <answer> - <p> - With JDK1.3, set the TOMCAT_OPTS (for Tomcat 3.X) or CATALINA_OPTS - (for Tomcat 4.X) as shown below (on Win2K) and then attach the debugger to - localhost:8000 using "<code>jdb -attach myhost:8000</code>" More information can be found at - <link href="http://java.sun.com/j2se/1.3.0/docs/guide/jpda/conninv.html";>JPDA - Connection and Invocation Details</link>. - </p> - - <source><![CDATA[ -set TOMCAT_OPTS=-classic -Xdebug -Xnoagent -Djava.compiler=NONE - -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=8000 + <faq> + <question>How do I debug Cocoon using JDK1.3+?</question> + <answer> + <p> + With JDK1.3 or above, first set the <code>CATALINA_OPTS</code> (for + Tomcat 4.x as shown below (on Win2K). + </p> + <source><![CDATA[ +set CATALINA_OPTS=-server -Xdebug -Xnoagent -Djava.compiler=NONE + -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=8000 ]]></source> - - <note> - This method is supposed to work under JBuilder4.0 as well. - </note> - </answer> -</faq> - - - + <note> + For Tomcat 3.x the param is TOMCAT_OPTS and the first value is + <code>-classic</code> instead of <code>-server</code>. + </note> + <p> + Add it to the <code>catalina.bat</code>, that can be found in + <code>%TOMCAT_HOME%\bin\</code>, right after the first <code>rem</code> + section. + <br/> + The same information in more detail can be found at + <link href="http://jakarta.apache.org/site/idedev-rdtomcat.html";>Setting + up Tomcat for Remote Debugging</link>. + </p> + <p> + The problem of this approach is the blocking of using Tomcat in another + mode. You always have to touch <code>catalina.bat</code> again when + changing the mode and this file is really a batch beast, isn't it? + Furthermore <code>catalina.bat</code> is only a starting mode library + and should not be touched by hand IMO.<br/> + Let me propose my approach: Go to the last line of + <code>startup.bat</code> where <code>catalina.bat</code> is called. + Replace + </p> + <source>call "%EXECUTABLE%" start %CMD_LINE_ARGS%</source> + <p>with</p> + <source> +set JPDA_TRANSPORT=dt_socket +set JPDA_ADDRESS=8000 +call "%EXECUTABLE%" jpda start %CMD_LINE_ARGS% + </source> + <p> + A switch can now be done by adding and removing <code>jpda</code>. You + can also place the old line in comments and switch between them. Or you + copy <code>startup.bat</code> to <code>debug.bat</code> and do the + changes there. + </p> + <note> + Note that Tomcat must be started using <code>startup.bat</code> in order + to set these values; if you are using + "<code>java.exe -jar ...bootstrap.jar start</code>" or anything similar to + start Tomcat, you have to set the <code>CATALINA_OPTS</code> on the + commandline or for Windows in general. + </note> + <note> + If you use Jetty included with Cocoon 2.1 it's much easier. Instead of + doing "<code>cocoon.bat servlet</code>" you simply call + "<code>cocoon.bat servlet-debug</code>". + </note> + <p> + After having started Tomcat or the servlet container of your choice in + remote debugging mode, attach the debugger to localhost:8000 using + "<code>jdb -attach myhost:8000</code>". If you get an error + "<code>Error accessing shared memory, rc = -1</code>", try + "<code>jdb -connect com.sun.jdi.SocketAttach:port=8000</code>" instead. + <br/> + More information on this can be found in the + <link href="http://java.sun.com/j2se/1.4.1/docs/guide/jpda/conninv.html";> + JPDA documentation</link>. + </p> + <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 <code>8000</code> and <code>dt_socket</code> are preselected. + </note> + </answer> + </faq> + <faq> + <question> + Now that I have prepared Tomcat and my IDE for debugging: How do I debug? + </question> + <answer> + <p> + 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.<br/> + 1. Set a breakpoint in a class via + "<code>stop in org.apache.cocoon.components.pipeline.AbstractProcessingPipeline.checkPipeline</code>". + <br/> + 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: + <br/> + <code>Breakpoint hit: "thread=Thread-11", + org.apache.cocoon.components.pipeline.AbstractProcessingPipeline.checkPipeline(), + line=363 bci=0</code>. + <br/> + 3. Use the debugger commands "print", "next", and "cont" to examine the + data and step through the code. + </p> + </answer> + </faq> </faqs> +
