Sitemap FAQs

What are the steps to pre-compile the sitemap and XSP's?

• Set the auto-reload to false in your sitemap.xmap as follows:

<parameter name="auto-reload" value="false"/>

• Use "-Dbuild.precompile=true" in your build command line when you are building your WAR file.

I don't want to hand edit the sitemap. Are there any tools?

Try this by Bruno Dumon.

How do I create some content which isn't directly visible to everyone?

Put the content in an internal pipeline...

<map:pipelines>
 <map:pipeline internal-only="true">
   <map:match pattern="int">
     <map:generate src="docs/description.xml"/>
     <map:serialize type="xml"/>
   </map:match>
 </map:pipeline>
 <map:pipeline>
   <map:match pattern="desc.html">
     <map:generate src="cocoon:/int"/>
     <map:transform src="stylesheets/description2html.xsl"/>
     <map:serialize type="html"/>
   </map:match>
 </map:pipeline>
</map:pipelines>

How can I concatenate two xml files?

<map:pipelines>
 <map:pipeline internal-only="true">
   <map:match pattern="one">
     <map:generate src="docs/one.xml"/>
     <map:serialize type="xml"/>
   </map:match>
   <map:match pattern="two">
     <map:generate src="docs/two.xml"/>
     <map:serialize type="xml"/>
   </map:match>
 </map:pipeline>
 <map:pipeline>
   <map:match pattern="desc.html">
     <map:aggregate element="newRootElement">
       <map:part src="cocoon:/one" element="firstXMLfile"/>
       <map:part src="cocoon:/two" element="secondXMLfile"/>
     </map:aggregate>
     <map:transform src="stylesheets/merge2html.xsl"/>
     <map:serialize type="html"/>
   </map:match>
 </map:pipeline>
</map:pipelines>

Where the element attribute names are replaced with something more meaningful! Note that the map:part element attributes can be left off, which results in the two parts being placed one immediately after the other.

I want to use the XXX matcher/serializer/selecter/etc but there's no examples :(

If you've checked the sample webapps which come with Cocoon, and you've looked in the documentation, then check both the user and dev archives. If it hasn't been resolved before first email the user group and, after a reasonable (i.e. 1 or 2 days) length of time (remember not everyone lives in your timezone) email the dev group.

Please don't cross-post to both the user and dev groups - very few people like getting bombarded!

Oh, and once you do get it working - how about documenting it and contributing it back to the group?

I changed the sitemap, but my changes don't show in the browser. Do I need to restart the servlet container?

Cocoon lets you decide whether it needs to poll for sitemap changes (with its associated performance penalty) or not. It also lets you decide whether the re-compilation resulting from polling shoud happen in the background or in the foreground.

If you look at the cocoon.xconf file, you'll notice this element:

<sitemap file="sitemap.xmap"
         reload-method="asynchron"
         check-reload="yes"/>

Which means:

• The check-reload attribute determines if the sitemap is reloaded on change. Set to "no", the sitemap is generated once at startup. Set to "yes", the sitemap is regenerated if it changes.
• The reload-method specifies the method for the regeneration:
  1. asynchron: If the sitemap changes, the sitemap is regenerated at the next request in the background and the incoming request is served with the old sitemap. All subsequent requests are served with the old sitemap until the regeneration in the background has finished.
  2. synchron: If the sitemap changes, the sitemap is regenerated at the next request. When the regeneration is finished, the request (and all subsequent ones) is served with the new sitemap.

For a development environment, set the reload-method to "synchron" and the check-reload to "yes." For a production environment, set the reload-method to "asynchron." For more safety, set the check-reload to "no."

In a nutshell: By default, reload is "asynchron" which means:

1. Change sitemap
2. Hit reload
3. Wait while CPU goes up to 100% and back down to 0%
4. Hit reload
5. Voila - new sitemap is used! :)

Hence: you don't need to restart the servlet container.

For sub-sitemaps, this issue is defined in the mounting element:

<map:mount uri-prefix="foo" src="file:///c:/foo/"
           check-reload="yes"
           reload-method="synchron"/>

With these settings Cocoon will react to any changes in the sub-sitemap, without even hitting the reload button twice. :)

Moreover, it is a good idea to use sub-sitemaps because they reduce overall compilation time. For example, changes to a single sub-sitemap won't require recompilation for the the main sitemap or other sub-sitemaps. This practice leads to greater degree of modularity.

When I add an action to a pipeline Cocoon returns an error.

Before the action was added to the pipeline it worked fine. After the change Cocoon seems not to find the file specified in the variable that is returned by the matcher.

<map:match pattern="*">
  <map:act type="validate-session">
    <map:generate type="serverpages" src="{../1}.xsp"/>
  </map:act>
  <map:serialize/>
</map:match>

Please note in the above example the "../1".

Map objects returned from matchers, actions etc. are organised hierarchically. Therefore they are not replaced by new ones but older ones are still accessible through a path expression. Here "../1" references key ("variable") "1" in the next to last Map.

What is the syntax for absolute filesystem pathnames.

In your sitemaps you may need to refer to some resource that is outside the webapp context (e.g. UNIX /foo/bar/this.xsl e.g. Windows C:\foo\bar\this.xsl). You need to use the file: convention.

• UNIX ... file:///foo/bar/this.xsl
• Windows ... file:///C:/foo/bar/this.xsl

See further explanation of file: URLs

What's the difference between having two pipelines with one matcher each, and one pipeline with two matchers?

If there is no other difference in pipeline declarations, then none, really. Note that pipelines can differ by:

• visibility: internal-only="true" (not accessible for external requests) or not.
• error handling: using different <handle-errors>s.
• cachability (since 2.1): some requests can use cached responses from caching pipeline. Others, which should not be cached, can be handled by the non-caching pipeline implementation.
• logical grouping: logically-related components can be grouped into separate pipelines to improve readability and ease administrative concerns.
• ids: used to identify pipeline and other elements. See the "sitebuilder" sitemap editor in scratchpad samples for an example.

Where can I find more information about the sitemap?

Learn more about advanced Sitemap features by downloading the free chapter, A User's Look at the Cocoon architecture, from Langham and Ziegeler's Cocoon: Building XML Applications available at the New Riders web site.

Check out a draft XML Schema grammar for the Cocoon sitemap, and some external documentation generated from this Schema. A poster diagram of the sitemap structure is also available.