Request Processing

This document tries to explain Apache Cocoon technically. We do this by describing what happens if somebody types in the URL of a simple Cocoon page.

The sequence of events described in this document, depends on some assumptions with regard to the configuration of Cocoon. That's what's described here.

The task of the sitemap is to define the pipelines that Cocoon will apply to URI's called in one's browser.

This is the minimal sitemap that is necessary. The lines here are included in the standard sitemap.xmap that comes with the distribution of Cocoon.

 
<?xml version="1.0"?>
          
<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0"> 
          
  <!--===========================Components================================-->
  <map:components>
          
    <map:generators default="file">
    <map:generator name="file" label="content" 
                   src="org.apache.cocoon.generation.FileGenerator"/> 
    </map:generators> 

    <map:transformers default="xslt">
      <map:transformer name="xslt"
                       src="org.apache.cocoon.transformation.XalanTransformer">
        <use-request-parameters>false</use-request-parameters>
      </map:transformer> 
    </map:transformers>

    <map:serializers default="html">
      <map:serializer name="html" mime-type="text/html" 
                      src="org.apache.cocoon.serialization.HTMLSerializer"/> 
    </map:serializers>

    <map:selectors default="browser">
      <map:selector name="browser" 
                    factory="org.apache.cocoon.selection.BrowserSelector">
        <browser name="explorer" useragent="MSIE"/>
        <browser name="netscape" useragent="Mozilla"/> 
      </map:selector> 
    </map:selectors>

    <map:matchers default="uri">
      <map:matcher name="uri" 
                   factory="org.apache.cocoon.matching.WildcardURIMatcher"/>
    </map:matchers> 

  </map:components> 
          
  <!--===========================Pipelines=================================-->
  <map:pipelines> 
    <map:pipeline> 
      <map:match pattern="hello.html">
        <map:generate src="docs/samples/hello-page.xml"/>
        <map:transform src="stylesheets/page/simple-page2html.xsl"/>
        <map:serialize type="html"/> 
      </map:match> 
    </map:pipeline> 
  </map:pipelines>
          
</map:sitemap>

<?xml version="1.0"?>

<cocoon version="2.0">

<!-- ===================== General Components =========================== -->

  <component role="org.apache.cocoon.components.parser.Parser" 
             class="org.apache.cocoon.components.parser.JaxpParser"/>
  <component role="org.apache.cocoon.components.store.Store"  
             class="org.apache.cocoon.components.store.MemoryStore"/>

  <component
      role="org.apache.cocoon.components.language.programming.ProgrammingLanguageSelector"
      class="org.apache.cocoon.CocoonComponentSelector">
    <component-instance name="java" 
      class="org.apache.cocoon.components.language.programming.java.JavaLanguage">
      <parameter name="compiler" 
      value="org.apache.cocoon.components.language.programming.java.Javac"/>
      <parameter name="code-formatter" 
      value="org.apache.cocoon.components.language.programming.java.JstyleFormatter"/>
      <parameter name="class-loader" 
      value="org.apache.cocoon.components.classloader.ClassLoaderManagerImpl"/>
    </component-instance>
  </component>

  <component role="org.apache.cocoon.components.classloader.ClassLoaderManager" 
      class="org.apache.cocoon.components.classloader.ClassLoaderManagerImpl"/>

  <component
      role="org.apache.cocoon.components.language.markup.MarkupLanguageSelector"
      class="org.apache.cocoon.CocoonComponentSelector">
    <component-instance name="xsp" 
        class="org.apache.cocoon.components.language.markup.xsp.XSPMarkupLanguage">
      <parameter name="prefix" value="xsp"/>
      <parameter name="uri" value="http://apache.org/xsp"/>

      <target-language name="java">
        <parameter name="core-logicsheet" 
value="resource://org/apache/cocoon/components/language/markup/xsp/java/xsp.xsl"/>

        <builtin-logicsheet>
          <parameter name="prefix" value="xsp-request"/>
          <parameter name="uri" value="http://apache.org/xsp/request/2.0"/>
          <parameter name="href" 
value="resource://org/apache/cocoon/components/language/markup/xsp/java/request.xsl"/>
        </builtin-logicsheet>

        <builtin-logicsheet>
          <parameter name="prefix" value="xsp-response"/>
          <parameter name="uri" value="http://apache.org/xsp/response/2.0"/>
          <parameter name="href" 
value="resource://org/apache/cocoon/components/language/markup/xsp/java/response.xsl"/>
        </builtin-logicsheet>
      </target-language>
    </component-instance>

    <component-instance name="sitemap" 
       class="org.apache.cocoon.components.language.markup.sitemap.SitemapMarkupLanguage">
      <parameter name="prefix" value="map"/>
      <parameter name="uri" value="http://apache.org/cocoon/sitemap/1.0"/>

      <target-language name="java">
        <parameter name="core-logicsheet" 
value="resource://org/apache/cocoon/components/language/markup/sitemap/java/sitemap.xsl"/>
      </target-language>
    </component-instance>
  </component>

  <component role="org.apache.cocoon.components.language.generator.ProgramGenerator" 
             class="org.apache.cocoon.components.language.generator.ProgramGeneratorImpl">
    <parameter name="auto-reload" value="true"/>
  </component>

  <!-- these components is used as a PoolController for the sitemap component pools  -->
  <component role="org.apache.avalon.util.pool.PoolController" 
             class="org.apache.cocoon.util.ComponentPoolController"/>

  <sitemap file="sitemap.xmap"/> 
</cocoon>

The role of Tomcat is to initialize the CocoonServlet, and to receive the HttpRequest and pass it on to the CocoonServlet.

This is done by calling CocoonServlet.init(ServletConfig). This is the standard servlet way to initialize a servlet.

On reception of a HttpRequest, Tomcat calls CocoonServlet.service(HttpRequest, HttpResponse). This is also standard.

Cocoon needs to know the classpath for compilation of the files it generates itself. This is where the classpath is stored.

The init file (normally cocoon.xconf, as defined in ${cocoon}/WEB-INF/web.xml) contains the necessary information for Cocoon to decide which classes to use for which roles (refer to Avalon).

This is a feature that is added for increased configurability. If you were developing a one time solution, the information in this file would normally be hard coded, but the use of this file increases potential reusability.

The init file is an xml file (normally cocoon.xconf) which describes the classes to use for which roles.

When the CocoonServlet gets a HttpRequest from the servlet engine, it sets up an Environment (a HttpEnvironment in this case) and passes that to Cocoon. The Environment exists of Request, Response, and some servlet info (such as requested URI and the servlet's path).

This Cocoon object lets the Environment decide which sitemap to use, and passes the sitemap filename along with the Environment to a Manager.

This one puts a Handler to work: it checks whether there already exists a Handler with a compiled version of the sitemap. If not, it creates one. This is what happens then:

This is the contact point for the servlet engine. It sets up the environment and passes all the work to a Cocoon object.

While this sounds to be the most important part of the Cocoon application, it is not. It is merely a Composable, meaning that it does some administrative work and gets other classes to work.

This is an Avalon interface. It assigns classes to roles. If an object needs a class for a specific role, it can ask a Configuration which class it has to use.

This one manages the sitemap: it finds out if there exists a Handler for a sitemap, and if not, makes sure that one gets created.

A class that is responsible for dealing with sitemaps. It holds the sourcefile of the sitemap, and the compiled code for it. It checks whether the sitemap class that it contains is still valid, and if not, regenerates it.

This one knows the markup of the sitemap, and helps writing the source file of the sitemap class.