apache > cocoon

How to run and explore the Cocoon samples


This How-To shows you how to run and explore the Cocoon samples. It requires no prior knowledge of Cocoon.


You will learn how install and run Cocoon in the simplest way, in order to run the Cocoon samples, and also how to study the samples from the inside to see how their are built.

Intended Audience

Beginning Cocoon users or people evaluating Cocoon for the first time.


You only need a JDK (1.3 or later) installed on your computer, and an Internet connection to download Cocoon.


Here's how to proceed.

1. Get Cocoon

Download Cocoon from the location listed on the cocoon.apache.org web site.

If you want the latest bleeding edge version, you can get it from CVS, this is described on the site as well, but more complicated if you're not familiar with CVS.

2. Build and start Cocoon

Unpack the Cocoon distribution and follow the instructions found in the INSTALL.txt file to build Cocoon.

If you have done this previously, make sure to remove any local.* configuration files that you might have created. You usually want to activate all Cocoon components to look at the samples, and local.* files might disable some components or even disable the samples.
Also, if you have already built Cocoon with a different configuration before, you might need to do a "build clean" first, to prevent any conflicts between different configurations.

The INSTALL.txt file also contains instructions for starting Cocoon with the cocoon.sh or cocoon.bat script, which is the simplest way and is sufficient to explore the samples.

3. Access the samples

Once Cocoon starts (and assuming you have kept the standard configuration), point your browser at http://localhost:8888, this should show the "Welcome to Apache Cocoon" page. On this page, click the samples link.

You should now see a page with links to many samples ( Hello World!, etc.), which show you what Cocoon is about. Note that there are several categories of samples: do not forget to look at the blocks with samples page, which contains samples based on components which are not part of the Cocoon core.

Another category is the scratchpad samples , these are based on experimental components that might or might not be included later in the Cocoon core or in a Cocoon block.

4. Study the samples

Now comes the interesting part: looking at the samples innards to find out how they are built.

This is fairly simple as the directory structure of the samples is similar to the URLs used to access the samples. These simple rules should help you find out much more about the samples:

  • If using the standard build configuration, samples are found under the build/webapp/samples directory. That's where you want to look to find out how a particular sample works.
  • Under this directory, the pathnames are the same then after the http://localhost:8888/samples base URL. The midi block samples, for example, are accessed from http://localhost:8888/samples/midi/ (note: the trailing slash is required) and the corresponding files are found under build/webapp/samples/midi.
  • When studying how a sample is built, it is recommended to first study its sitemap.xmap files, which map incoming requests to pipelines.


We hope that this How-To will help you explore the samples yourself, as this is probably the best way of learning about Cocoon.

Do not forget to look at the reference documentation though, once you have found out which Cocoon components you need for your application.


Care to comment on this How-To? Help keep this document relevant by passing along any constructive feedback to the cocoon-docs mailing list.