Updating Cocoon




Updating Cocoon

This is a brief discussion of the changes between the latest official release 2.0.4 and the current development version of Apache Cocoon. So, if you are interested in installing the official release, ignore this document. But if you want to know what is going on in the development of Cocoon, have a look...

Cocoon has developed many Avalon components which are of a more general nature. So, the best solution was to donate these components to the Avalon Excalibur project and move them out of Cocoon. This move has lead to some changes in configuration etc. which are described by this document.

In addition there were some disadvantages in the internal architecture of Cocoon. The new version removes these bottlenecks and gives more flexibility, usability and performance.


The Cocoon architecture has had some significant changes. However, great care has been taken that all changes are in a compatible way. This effort has been successful except one change which shouldn't affect anybody (see below).

Source Resolving

Under Cocoon 2.0.x, the SourceResolver was not an Avalon component, so it could not be looked up using a component manager. Under 2.1, the SourceResolver is now an Avalon component and can be requested using cocoon.manager.lookup(SourceResolver.ROLE).

XSLT Processor

Mention changes and update strategy...

XML Parser

The XML parser has also been moved to Excalibur. In the cocoon.xconf the hint name has therefore changed from parser to xml-parser. The configuration has not changed, so if you want to manually update swap the hint names.

From within your source code you should not lookup the org.apache.cocoon.components.parser.Parser.ROLE anymore; use org.apache.excalibur.xml.sax.SAXParser.ROLE instead.

XML Entity Resolver

The resolver used for resolving XML entities has also been moved to Excalibur. In the cocoon.xconf the hint name has therefore changed from resolver to entity-resolver. The configuration has not changed, so if you want to manually update swap the hint names.

From within your source code you should not lookup the org.apache.cocoon.components.resolver.Resolver.ROLE anymore; use org.apache.excalibur.xml.EntityResolver.ROLE instead.


The Store and StoreJanitor components and implementations have moved to Avalon Excalibur.

TODO:Changes in cocoon.xconf...

In general the packages changed from org.apache.cocoon.components.store to org.apache.excalibur.store (resp. org.apache.excalibur.store.impl). So if you have custom java code using this components, you have to change your imports.

The roles PERSISTENT_CACHE and TRANSIENT_CACHE have been renamed to PERSISTENT_STORE and TRANSIENT_STORE. The hold() method has been removed from the Store interface.

SAXConnectors, Stream and Event Pipeline

This is the only real incompatible change (But don't panic, this will not affect you, well at least only a little bit :). The internal architecture of Cocoon has changed. In the older version, the processing pipeline - constructed by a generator, the transformers and a serializer - was represented by two components, called stream and event pipeline.

For a simpler architecture, enhanced functionality and improved performance, these components have been combined into one: the processing pipeline. The very rarely used feature of SAXConnectors has been removed, to avoid overcomponentization.

In addition the map:pipeline element of the sitemap has gained more meaning as it is now possible to configure each map:pipeline section in the sitemap differently. So there can be one section using caching, another one not caching at all and a third one using a different caching implementation etc.

Changed Configuration

The configuration of the pipelines has moved from the cocoon.xconf to the sitemap. So, for updating you have to remove the "event-pipeline" and "stream-pipeline" section from your cocoon.xconf and add the map:pipelines section to the map:components section in your sitemap. You can find the pipelines components definition in the sample sitemap of Cocoon. Here is an example:

  <map:pipelines default="caching">
     <map:pipeline name="caching" 
     <map:pipeline name="noncaching" 

The configuration is similar to the configuration of other sitemap components, like generators or actions. You can choose these different implementations of pipelines in the map:pipeline section by specifying the type attribute:

     <map:pipeline type="noncaching">
           <map:match pattern="welcome">

So again, this is similar to choosing the type of the generator or any other sitemap component. If you omit the type attribute the default configuration from the components section is used.

The SAXConnectors have been removed, so if you manually upgrade you have to remove the sax-connectors configuration from the cocoon.xconf.

So you see, although this is an incompatible change in the Java code, you have only little to do to update your Cocoon installation.

Copyright © 1999-2002 The Apache Software Foundation. All Rights Reserved.