apache > cocoon

- Home

# WildcardURI-Matcher in Cocoon

## WildcardURIMatcher

NAME | wildcard
WHAT | The `WildcardURIMatcher` matches the request URI against a wildcard expression..
TYPE | Matcher, Sitemap Component
BLOCK | Core
CLASS | org.apache.cocoon.matching.WildcardURIMatcher
SINCE | Cocoon 2.0
CACHEABLE | not applicable

## Description

The `WildcardURIMatcher` matches a wildcard pattern against the requested URI.

## Usage

The `WildcardURIMatcher` is used to apply the same sitemap processing to a group of requested URIs. A requested URI belongs to this group iff the requested URI is matched by the specified pattern.

The snippet below applies to all requested URIs matching the wildcard pattern `page-*.html` the same specified pipeline processing. The generator retrieves the xml document having extension `.xml`, and its basename evaluated from the requested URI path, stripped off the prefix `page-`.

### Sitemap pipeline examples

The snippet below uses the `WildcardURIMatcher` for matching requested URIs of the form `page-*.html`.

    <map:pipelines>
      <map:pipeline>
        <map:match pattern="page-*.html">
          <!-- pipeline processing generator, transformer, serializing
          <map:generator src="xdocs/{1}.xml"/>
          <map:transformer src="stylesheet/document2html"/>
          <map:serialize/>
        </map:match>
      </map:pipeline>
      ...

### Sitemap component configuration example

The `WildcardURIMatcher` sitemap configuration consists of choosing a name, and specifying the src attribute of the fully qualified name of the WildcardURIMatcher class.

    <map:matchers...
      <map:matcher name="template"
        src="org.apache.cocoon.matching.WildcardURIMatcher"
        logger="sitemap.matcher.template"
        pool-max="32"/>
      </map:matcher>
    ...

### Configuration

The `WildcardURIMatcher` has no extra configuration as already mentioned above.

### Setup

The `WildcardURIMatcher` gets its wildcard pattern from the pattern attribute.

### Effect on Object Model and Sitemap Parameters

The `WildcardURIMatcher` accepts wildcard patterns. Wildcard patterns uses following matching algorithm

Pattern Token | Comment
--- | ---
** | Matches zero or more characters including the slash ('/') character
* | Matches zero or more characters excluding the slash ('/') character
\ character | The backslash character is used as escape sequence. Thus \* matches the character asterisk ('*'), and \\ matched the character backslash ('\').

The pattern '**' has higher precedence that two consecutive '*' patterns.

If matching succeeds `WildcardURIMatcher` returns a `Map` object. The entries of the map are the matched wildcard variable parts of the pattern. Accessing these matched values is accomplished by using sitemap parameter name of {N}. The N is ordinal number of matched variable part, starting with 0. The expression `{0}` represents the complete request URI, the expression `{1}` represents the first matched wildcard value, the expression `{2}` represents the second, etc.

In case of nested matchers, or actions the parent `Map` entries are referencable by using `../` prefix. Thus referencing the first wildcard matched value of a parent matcher in a child matcher it is expressed as `{../1}`.

In the snippet above `xdocs/{1}.xml` is expanded to `xdocs/index.xml`, if the requested URI was `page-index.html`.

## Bugs/Caveats

If a request URI starts with slash ('/'), the slash character is stripped off.

## History

12-28-02: initial creation

## See also

A general documentation about matchers is available at Matchers and Selectors.

Errors and Improvements? If you see any errors or potential improvements in this document please help us: View, Edit or comment on the latest development version (registration required).