Cocoon essentially is a large Java server application, most commonly deployed as a Servlet, capable of (mostly HTTP) request processing. Responses to incoming requests are generated by pipelines, consisting of several chained components. Communication between these components is done using SAX. The main pipeline components are Generators, Transformers and Serializers. The component deciding which pipeline to invoke is called the Sitemap. The Sitemap serves as the controller switchboard, declaring the applicable URIs of the web application, and the pipelines responsible for generating a response.

The sitemap is the central configuration mechanism of Cocoon. It is an XML document that is read by Cocoon, comparable to the (non-XML) httpd.conf file of the Apache HTTP daemon. Apart from a set of configuration declarations, it mainly consists of pipeline definitions inside by Matcher directives:

<map:match pattern="*.html">
  <map:generate src=”xdocs/{1}.xml"/>
  <map:transform src=“style/xdocs2html.xsl”/>
  <map:serialize/>
</map:match>

This pipeline will be invoked when a request hots Cocoon that mathes the *.html pattern. It will read an XML document from disk, stored in the xdocs directory, and apply an XSLT transformation onto it. The source XML document name is devised from the wildcard pattern - if the request was for the resource named "welcome.html", a "welcome.xml" document will be read from disk. After the XSLT transformation, the result is serialized as an HTML document and sent back to the browser.

In all its basic essence, this is how every request is handled in Cocoon: a lookup of the relevant pipeline in the sitemap, processing a SAX event stream by said pipeline, and serializing the result into a byte stream for network transport.

A huge variety of pipeline components exist in Cocoon. Passive components are responsible for generating, transforming and serializing content passed across the pipeline. There exist generators for reading documents from file or across the network using HTTP, free-form grammars can be XMLified using Chaperon (i.e. for reading CSV files), directory listings can be obtained in an XML format, and there also exists support for using JSPs as input for a pipeline. The archetypical transformer of course is the TRAX or XSLT transformer, but there is also an i18n transformer for translating marked sections in the SAX stream, and content can be injected based on SQL queries or LDAP lookups. Using a variety of external libraries such as FOP and Batik, responses can be sent back as XML, SVG, or even PDF and SVG formatted document.

Active components can be used to parametrize or alter pipeline behaviour, or to invoke business logic parallel to the request handling. The main active component is the matcher itself, which can select pipelines based on wildcard URI matches, regular expressions, or even request and session parameters. Browser-specific pipeline sections can be selected using the browser selector. For invoking logic orthogonal to the pipeline processing, actions can be used. These are primarly targetted towards handling authentication, database manipulations, sending mail or handling forms.

Using this combo of active and passive components, complex interaction can be defined without any programming. Should the included components not be sufficient for the needs of the application, custom components can be developed and used inside Cocoon.

For highly interactive web applications requiring the invocation of back-end business logic, Cocoon comes with its own web application development framework based on Flowscript and continuations. It also contains a comprehensive form handling framework, which supports strong typing of form variables, and makes the creation of forms and their binding to the back-end model (Java Beans, databases or XML) possible without much programming.

Using Flowscript, it is possible to isolate the flow of a web application into a powerful and easy to use Javascript file.

var email;

function newsletter()
{
  while(email == null) {
    cocoon.sendPageAndWait("email-form");
    
    email = cocoon.request.get("email"));
    
    if (!checkEmail(email))
    
      email = null;
  }
  cocoon.sendPage("registered", {who: email});

}

This sample snippet shows how an "email-form" page is sent back to the browser if the email parameter isn't known yet, and continues to send the "registered" page when the email address is provided using the form.

Cocoon comes with its built-in portal framework, and also houses a subproject Lenya that provides a content management framework. Furthermore, Cocoon is used by xReporter, an open-source web-based database reporting application.

All things Cocoon can be found at http://cocoon.apache.org/ - an actively maintained Wiki can be found at http://wiki.cocoondev.org/ (it is in the process of being moved to http://wiki.apache.org/cocoon/).