Mailing-List: contact docs-help@cocoon.apache.org; run by ezmlm
Precedence: bulk
Reply-To: docs@cocoon.apache.org
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
From: Apache Wiki <wikidiffs@apache.org>
To: docs@cocoon.apache.org
Date: Fri, 05 Jan 2007 22:47:02 -0000
Message-ID: <20070105224702.13768.38046@eos.apache.osuosl.org>
Subject: [Cocoon Wiki] Update of "DebuggingCocoon" by LarsHuttar

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Cocoon Wiki" for change notification.

The following page has been changed by LarsHuttar:
http://wiki.apache.org/cocoon/DebuggingCocoon

The comment on the change is:
added cross-references and clarifying notes

------------------------------------------------------------------------------
+ This page describes how to use a '''Java-level debugger''' to debug '''Cocoon itself'''. For notes on debugging Cocoon-based '''applications''', see also: DebuggingWithViews, ["DebuggingXMLandXSLTransformation"], and [http://cocoon.apache.org/2.1/userdocs/concepts/profiler.html Cocoon Profiler]. However, Java-level debugging can be useful for tracing Cocoon-based applications as well.
+ 
  On the [http://marc.theaimsgroup.com/?l=xml-cocoon-users&m=104722049132545&w=2 Cocoon users mailing list] ''Leszek Gawron'' wrote the original step by step guide to debug Cocoon using Eclipse or Swat. Now here's the wikified version.
  
+ Debugging Cocoon requires two steps:
+  1. Run Cocoon (in a servlet container) in a Java virtual machine (JVM) that has remote debugging enabled.
+  1. Tell your Java debugger/IDE, such as JSwat or Eclipse, to connect to the JVM process.
  
+ == 1. Run Cocoon with remote debugging enabled ==
- The easiest way to run Cocoon set up with remote debugging is to run
+ The easiest way to run Cocoon set up for remote debugging is to run
- 
- {{{cocoon.bat servlet-debug}}}
+   {{{cocoon.bat servlet-debug}}}
- 
  or
- 
- {{{cocoon.sh servlet-debug}}}
+   {{{cocoon.sh servlet-debug}}}
  
  '''Note:''' If you prefer to use tomcat for remote debugging, run: {{{$TOMCAT_HOME/bin/catalina.sh jpda start}}}
  
  The '''default debug port''' set in the {{{cocoon.bat}}} or {{{cocoon.sh}}} is port '''{{{8000}}}'''.
  
- And now:
+ The simplest way to test that your system is set up for remote debugging is to use jdb as described in step 2.
  
+ == 2. Connect your debugger/IDE to Cocoon JVM ==
+ 
+ === jdb ===
+ jdb is not generally recommended as a debugging tool because its user interface is very primitive. However, you can use it as a simple test case to make sure that your Cocoon JVM is set up to accept remote debugging connections. The jdb executable is typically found in the same directory in your path as the java executable. Type {{{
+ jdb -attach localhost:8000
+ }}} (for un*x/linux) or {{{
+ jdb -connect com.sun.jdi.SocketAttach:hostname=localhost,port=8000
+ }}} (for Windows).
+ A successful connection is indicated by {{{
+ Set uncaught java.lang.Throwable
+ Set deferred uncaught java.lang.Throwable
+ Initializing jdb ...
+ }}}
+ The error {{{java.io.IOException: shmemBase_attach failed: The system cannot find the file specified}}} will occur if you are on Windows and try to use {{{jdb -attach localhost:8000}}}; this will try to use shmem by default instead of sockets.
+ The error {{{Connection refused: connect}}} on Windows may indicate that the Windows Firewall is blocking the connection (it may not notify you of the blockage, even if configured to do so). Go to Control Panel / Windows Firewall / Exceptions / Add Port, and set Name = remote debugging, Port = 8000, TCP.
- ==  JSwat 2.3 ==
+ === JSwat 2.3 ===
   *  Attach to Cocoon VM.
   *  Set source path to:
    * {cocoon-cvs-home}\src\java
@@ -34, +52 @@

  
  Everything works quite fine but jSwat functionality is not enough for us. So lets switch to:
  
- ==  Eclipse ==
+ ===  Eclipse ===
-  *  LoadInEclipse.
+  *  LoadInEclipse. (You do not need to use SVN / Subclipse unless you want to stay on the bleeding edge of Cocoon internals, e.g. if you are a Cocoon committer.)
   *  Prepare new remote debug configuration (in your current project, so Eclipse will be able to resolve sources).
+   *  Run / Debug... / Remote Java Application / New
+   *  Fill in Name (of debug configuration); Host = localhost, Port = 8000. You may want to uncheck "Launch in background" on Common tab.
+   *  Click "Apply".
-  *  Attach to Cocoon VM.
+  *  Attach to Cocoon VM
+   *  Run / Debug...
+   *  Select your new debug configuration under Remote Java Application
+   *  Click the Debug button.
+   *  If you get "Connection refused", check your Windows Firewall (see above under '''jdb''').
   *  Browse your project for appropriate class, open the source file and set a breakpoint in a place you want to.
   *  Hit the page - wait for breakpoint to be triggered.
   *  Eclipse will open a source file and from now on you can step through the code.