Apache » Cocoon »

  Apache Cocoon

Apache Cocoon

Debugging Cocoon in Eclipse

This tutorial describes how you can run Cocoon in debug mode in Eclipse. Make sure that you have a working Cocoon web application. These two tutorials 

help you to get one.
Note: This tutorial describes how the Jetty Launcher can be used to run Cocoon. At the time of writing this, the Jetty Launcher doesn't support Jetty 6. If you prefer using it, find some instructions in the "Using Jetty 6" section.

Using the Jetty Launcher

  1. Install the Jetty Launcher Eclipse plugin using the plugin update link.
  2. After that, you have to download Jetty 5.1.x and extract it to a directory of your choice.
  3. Then follow the excellent Quick Start guide that comes with the Eclipse plugin.
Note: Jetty 5.1 does not support all of the Servlet 2.4 API, in particular the RequestAttributeListener which is used by Cocoon.  In order to run with the Jetty Launcher using Jetty 5.1, you must do the following additional steps:
  1. Copy etc/webdefault.xml from your Jetty 5.1 distribution to somewhere (e.g., the root directory of your webapp Maven module)
  2. Edit webdefault.xml, un-comment the JSR154 section at the end; this will enable Jetty's grudging support of RequestAttributeListener :-)
  3. In the Eclipse Jetty Launcher setup dialog, check the "Use a custom webdefaults config file" and enter the path to your webdefaults.xml
If you want to be able to debug code that is in one of your libraries,  you either have to add the source code to the dependency (if you use Maven 2 try mvn eclipse:eclipse -DdownloadSources) or if it is available as Eclipse project, add it as Project Reference / Java Build Path - Project reference. The second option together with the Reloading Classloader plugin, makes it possible to work in several projects while all changes take effect immediatly.

Using Jetty 6

Using the Jetty launcher is much simpler  and you don't have to create a Java project for each Cocoon application that you want to debug.If you prefer using Jetty 6, you can start Jetty as Java application from within Eclipse. For this purpose
  • download Jetty 6
  • and extract it into a directory of choice. You only have to make sure that it is not a subdirectory of an Eclipse project that is added to your Eclispe workspace.
  • now create a new Java project (e.g. "Jetty6") in your workspace and add jetty-6.x.jar, jetty-util-6.x.jar,  servlet-api.2.5.x.jar and start.jar as library dependencies (all 4 files are part of the official Jetty distribution)
  • add the project(s) that you want to debug as Project References and as Java Build Path - Projects references. This makes it necessary that these projects are added to the current workspace.
  • provide a minimal Jetty configuration file jetty-debug-cocoon.xml, e.g. in the root directory of your "Jetty6" project
<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Mort Bay Consulting//DTD Configure//EN" "http://jetty.mortbay.org/configure.dtd">
<Configure id="Server" class="org.mortbay.jetty.Server">
    <Set name="ThreadPool">
      <New class="org.mortbay.thread.BoundedThreadPool">
        <Set name="minThreads">2</Set>
        <Set name="lowThreads">2</Set>
        <Set name="maxThreads">10</Set>
    <Call name="addConnector">
          <New class="org.mortbay.jetty.nio.SelectChannelConnector">
            <Set name="port"><SystemProperty name="jetty.port" default="8080"/></Set>
            <Set name="maxIdleTime">30000</Set>
            <Set name="Acceptors">2</Set>
            <Set name="confidentialPort">8443</Set>
    <Set name="handler">
      <New id="handlers" class="org.mortbay.jetty.handler.HandlerCollection">
        <Set name="handlers">
         <Array type="org.mortbay.jetty.Handler">
             <New id="contexts" class="org.mortbay.jetty.handler.ContextHandlerCollection"/>
             <New id="defaultHandler" class="org.mortbay.jetty.handler.DefaultHandler"/>
             <New id="requestLog" class="org.mortbay.jetty.handler.RequestLogHandler"/>
    <New id="cocoon" class="org.mortbay.jetty.webapp.WebAppContext">
      <Arg><Ref id="contexts"/></Arg>
      <Arg>[path to the webapp root directory]</Arg>

    <!-- =========================================================== -->
    <!-- extra options                                               -->
    <!-- =========================================================== -->
    <Set name="stopAtShutdown">true</Set>
    <!-- ensure/prevent Server: header being sent to browsers        -->
    <Set name="sendServerVersion">true</Set>

  • open "Run - Debug" and add a new Java Application as debugging target
    • name it e.g. "Debugging Cocoon"
    • select the new project as Project
    • select org.mortbay.start.Main as Main class (check "Include libraries when searching for a main class")
    • add jetty-debug-cocoon.xml as Programm argument
    • add -Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog -Dorg.apache.cocoon.mode=dev as VM Arguments
  • hit the Debug button
  • open http://localhost:8080/[block-name] in your favorite web browser