Overview

The main goal for the new Cocoon 2.2 configuration system is to avoid patching of any provided configuration file (If you're familiar with previous versions of Cocoon you might remember the patching of the cocoon.xconf or web.xml to satisfy your project needs.) To reach this goal a new mechanism is used which provides features like automatic inclusion of configuration files, property handling and property replacement in configuration files. You will find more information about these things in the various documents about configuring Cocoon. But let's start with getting Cocoon up and running in your web application.

Cocoon is a framework consisting of many different components. All these components are managed by a component container. Starting with Cocoon 2.2 this container is the Spring framework. So the first step in setting up Cocoon is actually setting up the container and configuring the Cocoon components in the container.

Note: In previous versions of Cocoon, the container was setup by Cocoon itself which created a strong dependency between the container and Cocoon and made integrating Cocoon with other frameworks very difficult.

Note: You can get a skeleton Cocoon application by using the Cocoon archetypes for Maven 2 - so you don't need to do most of the stuff described here by hand. The Getting Started tutorial explains in detail how to use them.

There are various ways to setup a Spring container (have a look at the Spring documentation), but we suggest to setup a Spring application context using the context loader listener in your web.xml. In addition, Cocoon requires to setup Spring's RequestContext. The easiest way is to add Spring's request context listener for this purpose. Have a look at the Spring documentation for alternative configurations.

  ...
  <listener>
    <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
  </listener>
  <listener>
    <listener-class>org.springframework.web.context.request.RequestContextListener</listener-class>
  </listener>
  ...

This context listener is invoked by the servlet container on startup of your web application. By default the configuration for the application context is read from the file WEB-INF/applicationContext.xml. This is the place to add the global Cocoon configuration. Cocoon uses the namespace authoring features of Spring 2.0:

<beans xmlns="http://www.springframework.org/schema/beans""
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:util="http://www.springframework.org/schema/util"
       xmlns:configurator="http://cocoon.apache.org/schema/configurator"
       xmlns:avalon="http://cocoon.apache.org/schema/avalon"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
                           http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util-2.0.xsd
                           http://cocoon.apache.org/schema/configurator http://cocoon.apache.org/schema/configurator/cocoon-configurator-1.0.1.xsd
                           http://cocoon.apache.org/schema/avalon http://cocoon.apache.org/schema/avalon/cocoon-avalon-1.0.xsd">

  <!-- Activate Cocoon Spring Configurator -->
  <configurator:settings/>

  <!-- Activate the Avalon bridge -->
  <avalon:bridge/>

  <!-- Add your own spring beans here or in separate configuration files -->

</beans>

The two elements shown above are required to get Cocoon up and running inside your web application. The first one, configurator:settings, initializes the Cocoon Spring-Configurator. The second element, avalon:bridge, sets up the Spring-Avalon-Bridge. This bridge allows you to run Avalon-based components in a Spring container; these Avalon components are configured using the well-known Avalon-configuration files. And that's it.

These two innocent looking statements do a lot of work behind the scenes and add all necessary beans to the Spring application context. Once the application context is up and running, Cocoon is ready as well. You can either use the provided servlets to map requests to Cocoon or you can integrate Cocoon into your web application framework by getting the Cocoon beans from the Spring application context.

For more information on how to configure Cocoon, we suggest to read the documentation about the Cocoon Spring Configurator first and then continue with the other configuration documents.

Cocoon Core 2.2

Overview