Auto-Mount Cocoon Applications

by Bertrand Delacrétaz

Introduction

This document explains how to add a minimal application to the stock Cocoon 2.0.1 configuration, just by copying two files to a subdirectory, without changing anything to the existing configuration.

Part of the standard Cocoon distribution since Cocoon 2.0, the automount setup allows simple "applications" to be installed while Cocoon is running, without having to change anything to the standard Cocoon configuration. To see how this works, search for the word "automount" in the main sitemap.xmap.

Adding applications in this way is great for beginners to experiment without breaking anything, and can also be very useful for field installations of simple applications.

Note that this only allows simple sitemap-based applications to be configured: for now (Cocoon 2.0.1), configuration of additional components or database connections requires stopping Cocoon and editing global configuration files.

The example, step-by-step

  1. Locate the mount subdirectory of your Cocoon installation (webapps/cocoon/mount if you have a standard tomcat-based installation).
  2. Under this directory, create a subdirectory named mini-example.

  3. In the mini-example subdirectory, create a file named sitemap.xmap with the following content: 

    <?xml version="1.0"?>

<!-- minimal sitemap for Cocoon 2 test -->

<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">

  <!-- ======= Components ======= -->
  <map:components>
    <map:generators default="file"/>
    <map:transformers default="xslt"/>
    <map:readers default="resource"/>
    <map:serializers default="html"/>
    <map:selectors default="browser"/>
    <map:matchers default="wildcard">
      <map:matcher name="wildcard"
        src="org.apache.cocoon.matching.WildcardURIMatcherFactory"/>
    </map:matchers>
  </map:components>

  <!-- ======= Pipelines ======= -->
  <map:pipelines>
    <map:pipeline>
      <map:match pattern="">
        <map:redirect-to uri="somepath/somefile.html"/>
      </map:match>

      <map:match pattern="**/*.xml">
        <map:generate type="request"/>
        <map:serialize type="xml"/>
      </map:match>

      <map:match pattern="**/*.html">
        <map:generate src="cocoon:/{1}/index.xml"/>
        <map:transform src="request-to-html.xsl"/>
        <map:serialize type="html"/>
      </map:match>
    </map:pipeline>
  </map:pipelines>
</map:sitemap>

  4. Create another file named request-to-html.xsl in the mini-example subdirectory, with the following content: 

    <?xml version="1.0"?>

<!-- minimal XML to HTML example for Cocoon 2 -->
<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:req="http://xml.apache.org/cocoon/requestgenerator/2.0"
>

  <xsl:template match="/">
  <html>
    <body>
      It worked - this page was generated by Cocoon!
      <br/>
      The path of the XML data request was
      <font color="red">
        <b>
          <xsl:value-of select=".//req:request/@target"/>
        </b>
      </font>
    </body>
  </html>
</xsl:template>

</xsl:stylesheet>
  5. That's it! No need to restart Cocoon, requesting http://localhost:8080/cocoon/mount/mini-example/ (assuming a standard Cocoon installation, and don't forget the ending /) should give you an HTML page that says It worked and displays the request path.

This gives you a nice way of packaging simple applications needing only a sitemap and content/transform files, or using only components available in the standard distribution.

Have fun!