Orion Server: Configuring Apache Cocoon

Apache Cocoon is an open-source project from the Apache Software Foundation. It is an XML and Java based web-publishing framework. In a nutshell, it can apply XSL transformations to XML data, but on top of that it offers a lot of functionality.

Cocoon offers some significant advantages over the default XSL Servlet:

Pluggable processors to handle XML (e.g. XSL transformations, XSP logic, custom XML tags).
Multiple processor passes.
Stylesheet selection based on browser (e.g. Text browser, V5 browser, wireless device).
Pluggable result formatters (e.g. HTML, XHTML, WML, PDF, VoxML).
Customisable cacheing mechanism.
Easy switching of XML parser or XSLT engine.
Ability to process individual parts of a request (e.g. An XML include in an HTML page).
Open-source and massive community… always evolving.

XSP vs JSP

A substantial part of Cocoon is XSP (eXtensible Server Pages) which is an alternative to JSP. We’ll leave it to Cocoon XSP to explain what it is and why it’s needed.

If you’ve read that and think that’s wonderful, well you can use it. If you’ve read that and think the opposite and want to clutch onto JSP, well you can use that too. In fact, if you use any other technology for your dynamically generated XML (Servlets, PHP, Perl, etc), you can use them with Cocoon too!

Cocoon as a Filter

The latest version of the Servlet specification (version 2.3) defines Filters. A Filter can perform modifications to the data, headers and session in a request and response. Filters are designed to work alongside Servlets… Servlets handle the request and produce a response, the Filter can the modify this. Using Cocoon as a Filter allows any Servlet (including JSP, CGI, static pages, etc) to produce the XML, and Cocoon modifies it by passing it through it’s engine.

Using Cocoon as a Filter gives you all the functionality Cocoon offers as a standalone Servlet, but allows the data to be produced anywhere in the web-app. This means you are not confined to XSP or custom Producers.

Getting Cocoon

Download the latest version of Cocoon.

We recommend the latest 1.x version. This guide was written and testing using version 1.8.

Important: This guide is not designed for the experimental Cocoon 2.

Download the distribution and unpack into a suitable directory (it doesn’t matter where).

You will also require this package: cocoon-filter.jar. This contains the wrappers to allow Cocoon to function properly on Orion and includes the Filter extention.

Preparing Orion

From here on, [orion], [cocoon] and [web-app] refer to the directory Orion is installed in, Cocoon is unpacked in and your wep-app module is located in respectively.

Before continuing, the default XSL Servlet that comes bundled with Orion must be disabled. To do this, edit [orion]/config/global-web-application.xml and remove the following line:

<servlet-chaining servlet-name="xsl" mime-type="text/xml" />

Have a web-app to ready to install Cocoon in. If you are unsure where your web-app is located, it is the directory that contains your HTML files and in it’s root is a WEB-INF directory (most likely [orion]/default-web-app). When you have found your web-app, or created a new one, proceed to the next step.

Copying the Files

Copy the following files from [cocoon]/lib/ into [web-app]/WEB-INF/lib/ (if this directory does not already exist, create it):

# version numbers may vary
xerces_1_2.jar
xalan_1_2_D02.jar
fop_0_13_0.jar
turbine-pool.jar

Copy the file [cocoon]/bin/cocoon.jar into [web-app]/WEB-INF/lib/.

Copy the extra downloaded package cocoon-filter.jar into [web-app]/WEB-INF/lib/.

Copy [cocoon]/conf/cocoon.properties into [web-app]/WEB-INF/.

Optionally, you can copy the Cocoon samples directory [cocoon]/samples into [web-app]/. This is recommended so you can test Cocoon and get a feel for it.

Configuring the Web-App

Open the file [web-app]/WEB-INF/cocoon.properties in an editor and locate the following line:

producer.type.file = org.apache.cocoon.producer.ProducerFromFile

Place the following on the next line:

producer.type.filter = com.orionsupport.cocoon.ProducerFromFilter

Now locate the following line (not far below):

producer.default = file

And replace it with:

producer.default = filter

Finally, open [web-app]/WEB-INF/web.xml, and insert the following configuration inside the <web-app> tag:

<servlet>
  <servlet-name>cocoon-servlet</servlet-name>
  <servlet-class>com.orionsupport.cocoon.CocoonServlet</servlet-class>
  <init-param>      
    <param-name>properties</param-name>
    <param-value>/WEB-INF/cocoon.properties</param-value>
  </init-param>
</servlet>

<filter>
  <filter-name>cocoon-filter</filter-name>
  <filter-class>com.orionsupport.cocoon.CocoonFilter</filter-class>
  <init-param>
    <param-name>cocoon-servlet</param-name>
    <param-value>cocoon-servlet</param-value>
  </init-param>
</filter>

<filter-mapping>
  <filter-name>cocoon-filter</filter-name>
  <url-pattern>*</url-pattern>
</filter-mapping>

Done!

That’s it. If all went well then Cocoon should now be up and running. You can test by viewing the samples/index.xml file with your web-browser (remember to do it through the web-server, not directly from your local drive).

As well as handling .xml files, Cocoon will automatically kick in for any file that outputs a content-type of text/xml.