Galatea Information Strategies

Cocoon Overview

This FlashGuide^TM is meant to be a general introduction to Apache Cocoon.

Overview

Cocoon is officially defined as an "XML-based web publishing framework". What this means is that Cocoon is a mechanism for publishing XML data in a variety of formats. Cocoon is more than a simple XSLT engine, however. It provides interfaces to a variety of data sources, from simple XML files to database result sets, LDAP servers, XSPs, JSP scripts, etc. Optionally, various stages of logic can be applied to the extracted data, allowing for implementation of complex processing flows. Output formats include HTML, PDF, FOP, WML and raw XML.

Cocoon works by a pipeline model in which data is handed from one component to another in a chain. In its simplest form, input data is extracted from the data source, converted to SAX events, optionally processed, and converted into the output format. These pipelines are defined in a central configuration file, called the sitemap. Logic can be implemented in Cocoon in two main ways: XSPs and the sitemap. XSPs (eXtensible Server Pages) are roughly the Java equivilants of JSPs. They are XML files that include embedded Java logic. This logic can either be directly embedded in the XSPs or embedded via pre-defined logicsheets. Logic can also be implemented using the sitemap and specialized components like actions. This kind of logic focuses on conditional processing and parameter manipulation, using elements of the request and session objects.

Cocoon is developed under the auspices of the Apache Software Foundation. Cocoon was originally a DOM-based application known as Cocoon 1. Cocoon 2, the current SAX-based version, was first released in November of 2001. The current release is 2.0.2.

Why use Cocoon?

While there are plenty of XML publishing schemes around, Cocoon is successful in providing an entire publishing framework, not just a XML to HTML conversion utility. This means that you can do things as simple as XML to HTML conversion, but also complex, logic-driven aggregation of data from multiple sources. Cocoon's module framework allows easy addition of official or user-developed components. This framework includes robust logging, caching and connection pooling functionality.

Using Cocoon, however, does involve a certain commitment. Cocoon provides a conceptual separation of the tasks of developing content, logic and style. This means that organizations can divide up these tasks more easily than with traditional site development methodologies. Integrating this content, logic and style, however, can be a challenge. Because of its capabilities, Cocoon can also be complex to administer. This means that Cocoon users must be willing to take the time to learn this software thoroughly, so that they can use it to its potential.

Building Cocoon

There are no binary distributions of Cocoon available after the 2.0.4 release (the current release is 2.1.6). If you would like a binary distribution of 2.0.4, however, it is a very stable release and I highly recommend it. Personally, I've never had reason to upgrade from that version.

Check your prerequisites:
1. Make sure you have a Java Development Kit (JDK) installed, and the environment variable $JAVA_HOME set to the JDK installation directory. You should also have the $JAVA_HOME/bin directory in your $PATH. (For Windows users, make sure you have %JAVA_HOME set and %JAVA_HOME\bin in your %PATH
Download the latest Cocoon source distribution from http://cocoon.apache.org/mirror.cgi.
Unpack the distribution in the desired directory.
Cd into the source distribution directory:
```
cd cocoon-2.1.6
  
```
Build Cocoon with all the defaults. On Unix, type:
```
./build.sh
  
```
On Windows, type:
```
build
  
```
Or, you can tailor the build to your needs. For example, for production use I never build the samples. So, do this on Unix:
```
cp blocks.properties local.blocks.properties
  
```
On Windows, type:
```
copy build.properties local.build.properties
  
```

Now edit the local.build.properties file and uncomment the exclusions your desire. For example, to remove samples, documentation and test files, uncomment these lines:

# ---- Webapp ------------------------------------------------------------------

exclude.webapp.documentation=true
exclude.webapp.javadocs=true
exclude.webapp.samples=true
exclude.webapp.test-suite=true

# ---- Build Exclusions --------------------------------------------------------

exclude.deprecated=true
exclude.documentation=true
exclude.javadocs=true

If you previously built Cocoon, you should run a clean first:
```
./build.sh clean
  
```
On Windows, type:
```
build clean
  
```
Now build with the new build properties:
```
./build.sh
  
```
On Windows, type:
```
build
  
```
Finally, you can run Cocoon using its built-in web server, Jetty. This server will run on port 8888 by default, so make sure that port is not already in use:
```
./cocoon.sh servlet
  
```
On Windows, type:
```
cocoon servlet
  
```
Lastly, point your browser to http://[hostname]:8888, (where "[hostname]" refers to the machine on which you are running Cocoon), to see the default Cocoon page. Even if you have built Cocoon without samples, you will get a default page.

Learning resources

Learning Cocoon is not an easy task. Although there is good documentation in some areas, it is nevertheless difficult to get an overall grasp of Cocoon. Start with the documentation within the application. You can then try the Cocoon wiki at http://wiki.apache.org/cocoon/.

You can also check the Cocoon section of the Galatea LinkLibrary.

There are several books on Cocoon available. The most recent English one is my own, Cocoon Developer's Handbook, which I co-wrote with Jeremy Aston in 2002. There is also a more recent book in German, Cocoon 2 und Tomcat.

Back to Table of Contents