Apache Cocoon

Cocoon is an XML publishing system of the Apache Software Foundation. This framework was created to store data in XML form and output formatted with XSL. The output products of XML data XHTML, PDF, RTF and many more can (see below) are available.

" Cocoon is one, publishing framework servlet ', the [ ... ] transforms an XML source document, depending on the Requesting Client to any target format. "

The source code of Cocoon falls under the Apache license and is thus free software.

  • 4.1 Sitemap 4.1.1 Matcher
  • 4.1.2 selector
  • 5.1 generators
  • 5.2 Transformer / Transformers
  • 5.3 serializer
  • 5.4 Reader
  • 5.5 Action
  • 8.1 Flow Script
  • 8.2 continuations
  • 9.1 Design of Cocoon Forms
  • 9.2 Forms Processing


Cocoon was written in 1998 by Italian Stefano Mazzocchi students ( begun ), while he saw the sci-fi film Cocoon, after which the system was named.


The concept of Cocoon is based on a new approach compared to other web-based frameworks. For HTML documents, usually the layers content, layout and programming logic are firmly joined together, often even coded in a file. Cocoon is another way to release the information. The three mentioned layers are strictly separated from each other and must be processed in separate files. This means for the developer initially a greater effort when creating websites since it must create and maintain three files. This overhead can be multiple balanced with large projects in the course of development, as individual logic or layout parts can easily be replaced by changing the appropriate file integrated into other projects and thus recycled.

In order to implement the concept of separation of the individual layers in Cocoon, XML was chosen because XML satisfies these requirements consistently. About the three layers is the management that controls each part of the development.

In a Cocoon project a designer could, for example, be responsible for a style sheet (layout), a programmer for the logic, and a contributing editor for the contents of an XML file. Furthermore, Cocoon has been developed in Java, making it platform independent. Cocoon also helps to control the page flow ( Cocoon Control Flow), EAI requirements and the construction of web portals. In addition, it integrates seamlessly into the J2EE world.


Technically Cocoon is based on servlet technology. A servlet is a Java class that accepts client requests and processed on the Web server. In this processing, a response is generated, which is then in turn passed to the web server. Tomcat of Apache Software Foundation is the reference implementation of this technology, which uses the Java programming language developed by Sun Microsystems.

Using Cocoon can not only create dynamic Web applications, and the local use is possible. Apache Lenya is a content management system based on Cocoon.

In addition, Cocoon also comes with a portal engine that can create portals.


Cocoon has a fully object -oriented functional model. This makes it very easy to integrate or replace existing new components. All components are based on the model of Apache Excalibur, which specifies the exact structure of each component. There is the possibility to develop their own components, which can be integrated by inheritance in the existing model.

Cocoon 2

With Cocoon 2.x, the developers have decided to re-implement Cocoon to learn from the mistakes of the 1.x version. Has changed the internal architecture and the concept of Cocoon. Also added is the flexible Sitemap, with the processing instructions can be carried out in any order. Further, the performance was significantly improved - on the one hand by a faster caching technique, and further by optimizing the processing of XML - documents: Instead of using the DOM parser tree set up complex structures, the event-driven SAX parser is now used.

Through this reimplementation Cocoon has today two pillars: While the older concepts still exist, were added by the reimplementation of many new, necessary and helpful techniques. Because of backward compatibility, it is possible to use both older and newer techniques or to combine them even.

Cocoon 2.2

Since May 2008, the thoroughly revised version 2.2.0 of Apache Cocoon is marked as "stable". While the previous versions was the now set Apache Avalon framework based on the new version is based on Spring. Furthermore, the build tool Ant was replaced by Apache Maven.

Cocoon 2.2 is, like its predecessors, designed strong component- oriented. The development is now in independent modules, so-called block rather. This new architecture offers significant advantages, for example, by the Rapid Reloader class that automates the process of compiling Java source code, or the possibility of integration of functionality of the Spring framework. The handling (creation of blocks, block communication from each other, Eclipse integration, etc.) was significantly improved compared to its predecessors.


Cocoon is implemented on the basis of the Java frameworks Spring and can be extended to your own Java components. The actual work of Cocoon is executed in pipelines. The pipeline is composed of up to seven types of components each serving of the logic or to process.


The site map is the center point of each Cocoon application. The sitemap is an XML file sitemap.xmap by name. This is always located in the root directory of the current project. Subdirectories of the project may contain a Subsitemap. It defines the various components and the cocoon Client-/Server-Interaktionen in the so-called pipes. The purpose of a sitemap is to decide what happens when a specific request is requested by the user or by the system, such as calling a specific web page.

To identify what actions are performed for a specific request in order, the site map has called the Matcher.


User requests (requests, such as URLs or cookies) until a match is to be given in the sitemap tested against the Matcher. The answer (response) is then obtained from the execution of the Matcher associated tasks. The Matcher itself contain sequences of characters that match wildcards or regular expressions.


The selector evaluates certain information in the request. In this case, usually a HTTP header is transmitted when a Web page is requested. A selector represents a kind of switch statement

There are about 8 selectors available, only the most important:

  • Browser Selector ( check the browser used )
  • Host Selector (examination of the host parameter of the HTTP request )
  • Parameter Selector (examination of a defined parameter within Cocoons )
  • Header Selector (examination of the contents of the HTTP request header )


The Matcher and its associated tasks are referred to as an XML pipeline. A typical pipeline consists of a generator, possibly followed by one or more transformers, and finally a serializer.

The tasks within the pipeline are executed serially. Matcher are the link between a request ( by a client of Cocoon ) and executed subsequent operations of the pipeline.

The following figure illustrates the concept of the pipeline, in which a request is sent to the site map first, then the appropriate matcher called and the tasks are sequentially performed. The already mentioned several times, tasks are performed by so-called components that are integrated into Cocoon. The components that are used within the pipeline are a generator, a transformer and a serializer.


The generator is the starting point of the processing component of the pipeline. Generators have the task of structured data such as XML data or contents of a database, convert it to a SAX stream. This is then passed on to the transformer. There can be only one generator per pipeline.

Transformer / Transformers

Transformers convert the XML elements generated by the generator. There may be several optional transformers per pipeline. Each transformer often only cares about certain elements of the SAX stream. A plurality of transformers are carried out one after the other to produce a document with content and layout. Also, a pipeline without transformers is possible. The transformer is especially useful for websites with multilingual content application ( internationalization). Often a transformation step is performed using an XSLT stylesheet.


The serializer converts the output of the transformer, the SAX stream into a target document, in which the content can be then represented. The output is a stream ( binary or character ) and is sent as a response. Normally, a pipeline ends with the serializer.


The reader is suitable for very simple pipelines, since files can be returned without further processing to the client. It is mainly suitable for non-XML files in a Cocoon site.

Two readers are already included with Cocoon:

  • Resource Reader ( for reading binary data )
  • JSPReader (to read outputs from JSP pages )


An action used to control processes on a site. This dynamic runtimes are manipulated or performed operations on the server. Thus, an action does not generate data shown, but controls the flow within the pipeline.

Possible output formats

  • XML
  • HTML
  • WML
  • PDF
  • RTF
  • Excel
  • Flash
  • PHP
  • Etc.


A widespread and already used in Cocoon 1.x opportunity to develop Cocoon applications, the concept of eXtensible Server Pages is ( XSP ). An eXtensible Server Page is a normal and valid XML document. This includes i.d.R. a static content or certain features that capture a dynamic content from a data source (database, hash table, file). Unlike normal Java Server Pages the XSP file not HTML, but returns an XML document that provides the content for further transformations. The XSP document is passed directly to the generator, which converts it into a server page. The functions contained in the XSP document are converted to Java code. The XSP section has in addition to the possibilities already explained an optional logic component. This often contains JavaScript ( other languages ​​are theoretically possible). The logic component is integrated directly into the XSP document and has the task via POST request to examine or further process parameter passed. In this case, all the facilities are available, which are available to JavaScript. If a logic component in the XSP document integrates the strict separation of logic, layout and content is lost. This problem may be solved by the use of so-called logic sheets; However, this is only useful when used in large projects. Another ingredient that comes along with XSP used is the eXtensible Transformer Language ( XSLT). Its task is to process generated by the generator XML data further. To this end, the already mentioned Transformer be used. In order to control the operation of the generator and transformer, the Sitemap file must be adjusted. At this point, get the real strengths of Cocoon to the fore, since a very clear solution can be constructed by separating the logic and the layout can be in any time certain components replaced by others. For example, it is possible to give different XSP files to the generator of a pipeline, whereby the content of the web page, but not the layout changes.

Control flow

By introducing the concept of flow control ( Control -Flow) a Cocoon developers are options available that could be used only when a local application yet. Traditionally, Web applications over the stateless HTTP, which means that for every request a prompt response is generated without saving the state of the Web application, or to continue the program flow in the same place when re- request. Through unique session IDs in cookies and by URL rewriting is trying to avoid this circumstance in servlets. However, the program code is always passed from the front and branches on the basis of session IDs in different functions. This will quickly become confusing and complicated especially for larger applications. When working with forms and is stored values ​​appear especially on problems when the user tries to one or more pages to navigate back. There entered values ​​( POST or GET transmitted) can no longer be charged often. This allows the developer to take care of his application in the first place, was introduced with Cocoon 2.1 the concept of continuations in the context of flow scripts.

Flow Script

Flow Script is based on the widely used language on the Internet JavaScript. Since it is primarily intended to control the application process and not the integration of business logic into the Cocoon application that restrictions against Java are not disturbing. If complex processes and models required, they can be imported in the form of Java classes in JavaScript.


A common problem in the web is that incurred entries have disappeared on a web page when reloading this page. In Cocoon, this problem was completely solved by the concept of continuations. A continuation is generated within the flow scripts. This is done automatically by calling cocoon.sendPageAndWait (). A Continuation object has the task to save the current state of the program, including the program counter ( the point in the flow scripts ), all local variables and input from the user as well as the stack. The Continuation object is automatically assigned when you create a unique ID. After generating the continuation of this is stored in a global hash table, and can be loaded again when required. At this time the Continuation object is empty. After putting in the hash table the desired website is sent to the user. The Flow Script stops after execution of the cocoon.sendPageAndWait () command and waits for an input from the user. Only then is the flow script is continued. After the user inputs his - for example in a form - has made, it sends the data entered and requests the current, stored in the hash table Continuation object. This stores the values ​​that were entered by the user in the web form. Only now is the Continuation object is fully processed and may at any time be loaded with the values ​​entered by the user again.

The use of continuations is only useful when a real interaction takes place with the user.

The following flowchart in Figure illustrates summarized the completion of a continuation of all flow control Components.

Cocoon Forms ( Woody )

By far the most powerful form framework, which is currently available in Cocoon, called Cocoon Forms ( cforms ). It offers a variety of options, such as form validation, creating pop-ups and simple integration of visual graphic elements. Forms is currently in the development stage, so it is possible that certain elements will change. For example, Forms was developed to Cocoon version 2.1.4 still under the code name Woody. When changing to Cocoon version 2.1.5 the name and thus all library names and paths have changed. Forms will be the official standard framework for forms processing.

Construction of Cocoon Forms

The concept of Forms separates like almost everything in Cocoon, the content of the logic and layout. For this reason, there is a form that was created with Forms, of two files:

  • Form definitions
  • Form templates

Form definitions describe the individual elements that are needed in a form. A form definition file does not contain presentation data. Therefore, it can be recycled along with any number of presentation files. The elements in the form definition file are referred to as so-called widgets. The developer is doing a large number of widgets available, for example buttons, edit boxes or combo boxes. Each of these widgets can be with an individual appearance, behavior, and even provided with functions. To enable widgets in a particular behavior, there are very complex ways, starting with the reference to the name and description of an object above the declaration of simple data types, which can take a widget up to run JavaScript code in by certain predefined events Widget is triggered.

Form templates are in principle XSL transformation files. They contain the presentation logic and bind the individual widgets. It must not be involved all widgets of a definition file. In addition, the form template defines certain properties such as size and color of each fixed widgets.

Forms processing

To create a web page with Forms, Special Forms transformers and Forms generator must be used. In addition, the whole concept of flow script must be controlled.