Built with Apache Lenya

URI Parametrizer

Table of Contents

Motivation
Rationale
- Overview
- Interfaces

Motivation

The problem of determining the doctype independent of request URI needs a flexible and yet simple solution. This is where the URI Parametrizer comes to the rescue.

Rationale

The URI Parametrizer is an action which given an arbitrary URI return a configurable number of parameters which it infers from this URI. Typical parameters include source document type, navigation location, etc. The action itself delegates to task of determining the parameters to the Cocoon sitemap, i.e. the parameters are determinined using the normal sitemap pipeline matching mechanism.

Overview

The flow of information is outlined in the following diagram:

Interfaces

The URIParametrizerAction expects an arbitrary number of parameters. Each parameter contains a key value pair which denotes the name of the parameter and the source. A typical example is as follows:

<map:act type="uriparametrizer">
  <map:parameter name="doctype"
	  value="cocoon://uri-parameter/{publication-id}/doctype"/>
  <map:parameter name="path"
	  value="cocoon://uri-parameter/{publication-id}/path"/>
  <map:generate src="cocoon:/{doctype}/{path}"/>
</map:act>

The uri-parameter prefix is a standard prefix which invokes a pipeline in the root sitemap which mounts a subsitemap in your publication with the name parameter-{parameterName}.xmap.

The action basically just issues a request back to cocoon for each parameter. It uses the URI given in the value attribute where it also adds the original request URI. So for a given request URI foo.html and the parameters given above the action basically issues to requests using the cocoon: protocol:

cocoon://uri-parameter/{publication-id}/doctype/foo.html
cocoon://uri-parameter/{publication-id}/path/foo.html

The matcher for uri-parameter in the root sitemap then tries to mount the sitemaps parameter-doctype.xmap and parameter-path.xmap in the publication. Then the reuest is matched against the parameter sitemap. Here's a very simple example of a parameter sitemap:

<?xml version="1.0"?>

<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">

  <map:components>
    <map:generators default="file"/>
    <map:transformers default="xslt"/>
    <map:readers default="resource"/>
    <map:serializers default="html"/>
    <map:matchers default="wildcard"/>
    <map:actions/>
  </map:components>

  <map:views/>

  <map:resources/>

  <map:pipelines>

    <map:pipeline>
      
      <map:match pattern="**">
	<map:generate type="serverpages" src="content/parameters/doctype.xsp">
          <map:parameter name="value" value="{1}"/>
        </map:generate>
	<map:serialize type="xml"/>
      </map:match>
      
    </map:pipeline>

  </map:pipelines>
</map:sitemap>

A more serious example could possibly include matchers using the SourceTypeAction from the Forrest Project or a HashMapAction as outlined in the SiteTree proposal.

After a match has been found the pipeline in the parameter sitemap returns an XML snippet in the following form:

<?xml version="1.0" encoding="ISO-8859-1"?>

<parameter xmlns="http://apache.org/cocoon/lenya/uri-parameters/1.0">article</parameter>

This xml is consequently parsed by the action and returned as a HashMap. Inside the action the parameters will be available under the names as they were specified in the parameters to the action.

The fact that the actual determination is delegated back to the sitemap allows for a combination of the original proposals where solutions such as Hashmap and SourceTypeAction were outlined.