Building XML Portals with Cocoon

July 24, 2002

Carsten Ziegeler and Matthew Langham


Cocoon is an Apache open source project originally started by Stefano Mazzocchi in 1998 because he was frustrated by the limitations HTML poses when it comes to separating content from design. He described the current Cocoon version in detail in an article for in February.

Although Cocoon was originally designed as a framework for XML-XSL publishing, we felt that due to the extensibility of the architecture, it would be possible to add components that extended Cocoon so that it could be used in a wider variety of applications. Around the same time we decided to use Cocoon, we were also evaluating available commercial portal solutions for several customers. Portals used in a more commercial environment have varied requirements. Therefore it seemed ideal to extend Cocoon with components for authentication and portals -- and at the same time to retain the original strengths of the platform.

The new components were originally developed as part of a commercial offering. In the middle of 2001 we installed the first Cocoon-powered portal at a financial institution in Germany. At the beginning of 2002 we then donated the components to the Cocoon project. The donation consisted of components and tools for authentication (originally called "sunRise") and portals (originally called "sunSpot"). Each part can be used without the other; the authentication can be used to protect certain resources on the server.

In this article we will look at the Cocoon portal and authentication frameworks, and we assume that the reader is familiar with the basic Cocoon concepts, such as the sitemap. You can find an introduction to Cocoon in a recent article by Steve Punte.


Authenticating a user is one of the central aspects of any modern middleware application. Once the user has been authenticated, she should be able to access the preconfigured resources for her particular user-id or role.


The goal of the contained authentication components is to allow the authentication of a user against a configured user data-source (such as a database). The components should also allow resources to be protected, meaning that they can only be accessed if the authentication was successful. The most important goal was however to make sure all this is possible using the original Cocoon concepts which allow a great deal of flexibility when it comes to connecting to external systems.


The authentication framework consists of additional Cocoon components that provide the necessary functionality. New components are provided for session handling and for allowing data to be stored in and retrieved from a user's session. In addition a Cocoon "action" component can then be used to protect the resources.

The concept of authentication-handlers was introduced to allow the logical grouping of resources. This means that once a user has authenticated herself against a particular handler, she can access all the resources that have been logically grouped under that particular handler. Each handler can then be configured to authenticate against a particular-data source, so handler A could authenticate against a database and handler B could use an LDAP directory. The actual authentication takes place using Cocoon pipelines.

Here is a snippet from the Cocoon sitemap. It shows how a handler is configured.





                <handler name="portalhandler">

                    <redirect-to uri="cocoon:/sunspotdemoportal"/>

                    <authentication uri="








The different handlers are grouped inside the authentication-manager section. Each handler has a unique name which can be referenced later when configuring the pipelines that needs to be protected. The redirect-to tag is used to configure the pipeline that is to be called if the user tries to access a protected page which she is currently not allowed to see. The authentication pipeline is defined in the tag authentication. This pipeline receives the input from, say, a login screen and can then authenticate the data against a data-source such as a database.

If successful, the authentication pipeline (in this case a pipeline called "sunrise-authuser") is required to return XML data in a specific format which is described in detail in the Cocoon documentation. The format is flexible: additional data about the user can be added by the authentication pipeline and used in the application at a later stage.

Once the handler has been defined and the authentication pipeline configured, the next step is to protect the resources. The following XML fragment taken from the sitemap, shows how a resource can be protected using the authentication action in conjunction with the defined handler.

<map:match pattern="protected-document">

    <!-- protect this document -->

    <map:act type="auth-protect">

        <map:parameter name="handler" value="portalhandler"/>

        <map:generate src="document.xml"/>

        <map:transform src="to_html.xsl"/>




In this case the resource protected-document "belongs" to the handler called portalhandler. If the user has previously logged into that handler, then all the resources grouped under that particular handler will be accessible to her. If the user has not already logged in, then she will be redirected to the pipeline previously defined when the handler was configured. Normally a login-screen will then be presented and the user can log in with an id and password.

Along with the components that can be used to protect the pipeline, Cocoon also offers several browser-based tools that will let you maintain a user database and configure new users or roles without having to edit the underlying XML by hand. Because the different functions (such as "add user" etc.) are mapped to specific pipelines inside the authentication framework, it is easy to configure the tools so that say an existing data-source can be used instead of the sample XML file which is provided in the distribution.

Tool for user  management

Using the sample authentication setup provided in the distribution, it is easy to build prototype solutions that can be reconfigured from a test database to the production database by just changing the handler configuration. As mentioned, the authentication components can be used on their own to provide access control to any type of application built with Cocoon.


Because of the vast amount of information available on the Web, portals have become a common tool which provides a personalized view on that information. A portal normally consists of the user authentication and the personalized content view. The content view is generated from several different sources, such as news or weather feeds. This is of course dependent on the type of portal being built.

When we evaluated available portal solutions for our customers, it quickly became clear that the "out-of-the-box" solutions were not flexible enough to meet the varied requirements of our customers. Because of the increased need for "multi-channel" solutions (i.e. publishing to different formats such as HTML, WML or PDF) and the requirement that the portal be able to connect up to varied data sources, we decided that adding portal components to Cocoon would provide an ideal solution.


The most important goal of the Cocoon portal was to maintain Cocoon concepts, in particular the flexibility of using pipelines to access the various data sources and the use of XML inside the platform. The solution should provide typical portal functionality, such as the ability to configure the layout of the portal or for the user to be able to decide which data-feeds she would like to see. The portal configuration (available portlets etc.) and the portal view should be described using XML. The layout of the portal should be done using stylesheets, so the portal can be generated for the needed output formats, like HTML, WML or even PDF. Using stylesheets to layout the portal would also allow for flexible generation based on information such as the type of browser used or whether the user prefers a "tabbed" portal or not.


In order to authenticate a portal user, the portal uses the Cocoon authentication components described above. This allows existing user databases to be used as a storage for portal users. The portal framework contains additional Cocoon components for the portal generation and configuration. Accessing different data sources, known as portlets in most of the portal world (Cocoon calls them "coplets"), can be done via pipelines, URIs, or even Java classes which implement the coplet interface.

Using XML as the format for the portal (that includes profiles and coplet configuration) means that the portal can be extended as needed. The portal demo which is included in Cocoon has typical portal features like minimizing or maximizing a coplet, changing colors, or rearranging the layout.

An example portal

The portal view a user receives is described in XML. When the user logs into the portal, various steps are performed to build the user-specific portal. The build process begins with two base profiles, the definition of the coplets, and the definition of the portal layout. The following XML snippet shows the definition of a coplet called "sundnnews". Notice how the definition of the resource uri maps to a pipeline inside the Cocoon sitemap. This example shows how a normal Cocoon pipeline can be used as the source for a coplet.



        <coplet id="sundnnews">

             <resource uri="







             <title>s&n News</title>










The base layout profile describes the layout of the portal, such as which style (column or tabbed) is to be used and whether a footer or header is available.

The first step in the build process combines these two base profiles into a global profile. This global profile is the starting point for specific profiles which can be dependent on the user's role or id. The portal administrator can define different default portals for a specific role; for example, a default portal for an administrator or a default portal for a guest. This role profile inherits everything from the global profile and the administrator can then change specific details for the defined role.

The next step is to configure the role profile dependent on the user's configuration. Each user can have her own profile, which in turn inherits from the role profile. Once the profile has been built, it is then cached. When the user logs in next time, the cached version is used instead of recreating it from scratch. In addition, the Cocoon portal keeps track of changes in the profiles. If a base profile is changed, the cached version is invalidated and the next time the user logs in, the changes will take effect and the portal profile is rebuilt.

Here is the actual pipeline from the sitemap that builds the portal. It consists of a specialized portal generator component. As with any Cocoon pipeline the actual layout of the portal is defined using a stylesheet.

<map:match pattern="sunspotdemo-portal">

    <map:act type="auth-protect">

        <map:parameter name="handler" value="portalhandler"/>

        <map:parameter name="application" value="sunspotdemo"/>

	<map:generate type="portal"/>

        <map:transform src="styles/portalHTML.xsl"/>





As you can see, the authentication framework is used to protect the portal, so only logged in users can view their portal. The application parameter allows the portal framework to retrieve the configuration for the portal.

Tool for portal management

The Cocoon portal also provides tools so that the portal configuration can be done without having to edit the underlying XML files. As contained in the Cocoon distribution, the example portal brings all the described concepts to life and can be used as the starting point for an individual solution.

Once you have explored the example portal you can start altering it to fit your needs. Obviously you can add new coplets, by defining the pipeline inside the Cocoon sitemap and adding the pipeline as a coplet using the included tool. Because of the way the portal allows new data sources to be included using Cocoon pipelines or URIs, new portals can be built without having to write any code. Another interesting aspect is using an additional stylesheet in the portal generation pipeline to change the appearance of the portal. Cocoon offers components, such as selectors, that can be used to select a different stylesheet depending on the type of browser or other external parameters. Imagine a "late-night" portal, where the layout is changed after 8 PM using a different stylesheet.


The portal and authentication components were donated to the Cocoon project at the beginning of 2002, and they are already being used by several large companies as the base for Intranet based offerings. We are particularly proud of the fact that NASA and large IT companies such as BASF IT Services have seen the advantages of using an open source, XML-based solution to provide a powerful enterprise portal. Because the portal is tightly integrated into the XML publishing platform, it does not break Cocoon concepts and allows the flexibility of XML-XSL publishing to be utilized.

The current portal can be thought of as version 1.0 and has been in production use for over a year. The next version of the portal aims to increase the flexibility of the system and to introduce conformance to existing and emerging portal standards.


Introducing Cocoon 2.0

Apache Cocoon Project

Cocoon Portal first look

Cocoon XML Portal at O'Reilly Open Source Convention