cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Leigh Dodds" <>
Subject Virtual Hosts/Mounts (was RE: Newbie questions)
Date Mon, 05 Aug 2002 15:59:31 GMT

>>Michele Neylon
>> 1. I would like to be able to offer it to a couple of virtual hosts on
>> my server and was wondering what was the best method.

>Vadim Gritsenko
> There are couple of ways:
> 1. Have single Cocoon instance serving requests to all virtual hosts.
> Use host matchers/selectors to select resource to serve.
> 2. Have single Cocoon instance with sub-sitemap for every host. Put
> apache in front of Cocoon with rewrite module.
> Sorry, don't have configuration examples - didn't had need for multiple
> hosts.

Here's a document that I've been working on which should help you 
ought with how to do sub-sitemaps. The additional configuration steps 
will be to use the Host selector -- I believe there's an example of 
this already in the Cocoon docs.

If anyone has any feedback on the following please let me know, it 
was quickly drafted on a train journey so hasn't been thoroughly 
proof-read. (Also forgive the scraps of Wiki markup, it's extracted 
from my personal wiki site, and the cross-posting -- hoping 
for sanity checks from the developers also)

btw, was a separate mailing list for Cocoon documentation ever 
created? IIRC there as a proposal to do so recently?


!!Understanding Cocoon Mounts

!The Root Sitemap

The default Cocoon web application reads the sitemap.xmap file 
in the $webapp_home directory for instructions about how to 
process incoming requests.

This means that if the Cocoon web application is installed in 


Then all requests with the base URL of:


will be serviced by asking this sitemap for a suitable pipeline.
The matchers defined in that sitemap can allow for arbitrary 
amounts of additional path information, but it is this initial 
root 'mount point' that determines basic request processing.

So for example a pipeline with:

<map:match pattern="my/long/url/path/*.html"/>

Will match:


So while the Cocoon web application is mounted at /cocoon 
in the servlet container. The pipelines are mounted from 

However placing all pipeline and component configurations in 
a single sitemap can be unwieldy, it's better to partition up the 
web application. This can be done by creating additional sitemaps 
which contain related functionality. E.g. all form processing 
relating to registration, searching, etc.

!Mounting Sub-Sitemaps

Partitioning a sitemap in this way involves use of the <map:mount/> 
element. This indicates that a second sitemap should be processed, 
and includes the location of that sitemap.


<map:match pattern="my/long/url/path/*.html">
 <map:mount src="my/long/dir/structure/sitemap.xmap"/>

Will cause the sitemap in $TOMCAT_HOME/cocoon/my/long/dir/structure/ 
to be queried for pipelines that can process this request. The second 
sitemap is referred to as a ''sub-sitemap''. It inherits all component 
declarations from it's parent, so there is no need for them to be redeclared.
However the empty container elements (e.g. <map:generators/>) must 
still be provided for the sitemap to be parsed correctly. These elements 
can indicate the name of the default component as usual.

However, any matchers in this sitemap would still have to 
use the full request path for their match to work as expected

I couldn't do:

<map:match pattern="*.html"/>

As this actually matches


To enable additional unwanted path information to be ignored, 
we need to add an additional uri-prefix attribute to the <map:mount>
element, as follows:

<map:match pattern="my/long/url/path/*.html">
 <map:mount src="my/long/dir/structure/sitemap.xmap"

Which means that a matcher with the pattern *.html in 
$TOMCAT_HOME/cocoon/my/long/dir/structure/sitemap.xmap will 


but not


The other additional parameter to the mount element is check-reload 
which can have the value yes or no. This indicates whether the mounted 
sitemap should be reloaded if it changes.

!Location Independence

Note also that the sitemap location is completely separate to the 
path info in the URL. I can maintain my sitemap.xmap file anywhere 
on the file system that can be read by Cocoon. As is usual in Cocoon 
pipelines, it's the matching components that dictate how a request 
path is tied to a sequence of processing.

!Partitioning Options

The above example have assumed that the Cocoon application has 
been partitioned into a collection of sub-sitemaps according to 
the request path.

However it's perfectly acceptable to partition an application based 
on any criteria. In fact any selector or matcher component can be 
used as the means to delegate processing to a sub-sitemap.

So, for example I could use the HostSelector to select an alternate 
sitemap based on the host name used in the request. Or I could 
use the BrowserSelector to separate processing based on user-agents.
The ParameterMatcher could select sub-sitemaps based on request 
parameters, and so on.


Extending this facility to its natural conclusion, we can use the 
power of the WildcardMatcher component and the <map:mount/> 
element to create an 'auto-mount' feature that will allow sitemaps 
underneath a given directory structure to be automatically loaded 
by Cocoon.

We can achieve this with the following:

<map:match pattern="auto/*/**">
   <map:mount uri-prefix="auto/{1} src="auto/{1}"/>

This uses wildcard, and sitemap parameters to automatically match 
a base request url, in this case:


The first path element is matched and stored in {1}. This is 
then used as the name of the directory from which to load 
the sitemap. In this case a request for


Will cause the sitemap in:


to be loaded and the prefix /auto/foo/ automatically 

Auto-mounting can use the flexibility required earlier to auto-mount 
sitemaps based on request parameters, and a whole range of 
other options. However doing so using a correlated request-path 
and directory structure makes the functionality more intuitive.

!Auto-Mounting and Users

Auto-mounting is a good way to allow multiple users to share a 
Cocoon instance. Their public_html directories can be symbolically 
linked to the 'auto' directory, and they can then operated independently 
of one another.

!Sub-Sitemaps and Components

Since Cocoon 2.0.X it has been possible to include additional cocoon.xconf 
files in sub-directories. These will be automatically processed by Cocoon, 
allowing the declaration and use of additional components, JDBC connections, 
etc. Again this enables multiple users to more easily share a single 
Cocoon instance.

It also provides a fairly clean way to package a Cocoon application for 
sharing with others: create a directory complete with sitemap.xmap, cocoon.xconf 
if required, and all additional supporting files. This package can then be passed 
on to others who can install it by simply unpacking it into their file-system 
and adding the appropriate mount elements into their root sitemap (or one of 
it's sub-sitemaps).

In this way, a service provider can also choose to host Cocoon applications 
for others.




Leigh Dodds
"Pluralitas non est ponenda sine necessitate" -- William of Ockham

To unsubscribe, e-mail:
For additional commands, email:

View raw message