| <?xml version="1.0" encoding="UTF-8"?> |
| <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd"> |
| |
| <!-- |
| <![CDATA[ CVS Version: $Id: wildcarduri-matcher.xml,v 1.3 2003/10/12 13:04:51 cziegeler Exp $ |
| ]]> |
| --> |
| |
| <document> |
| <header> |
| <title>WildcardURI-Matcher in Cocoon</title> |
| <version>0.9</version> |
| <type>Technical document</type> |
| <authors> |
| <person name="Bernhard Huber" email="huber@apache.org"/> |
| </authors> |
| <abstract>This document describes the WildcardURIMatcher of Cocoon.</abstract> |
| </header> |
| <body> |
| <s1 title="WildcardURIMatcher"> |
| <table> |
| <tr> |
| <td>NAME</td><td>wildcard</td> |
| </tr> |
| <tr> |
| <td>WHAT</td><td>The <code>WildcardURIMatcher</code> matches the request URI |
| against a wildcard expression.. |
| </td> |
| </tr> |
| <tr> |
| <td>TYPE</td><td>Matcher, Sitemap Component</td> |
| </tr> |
| <tr> |
| <!-- choose Core, the block name, or Scratchpad |
| depending on where WildcardURIMatcher sources live |
| --> |
| <td>BLOCK</td><td>Core</td> |
| </tr> |
| <tr> |
| <td>CLASS</td><td>org.apache.cocoon.matching.WildcardURIMatcher</td> |
| </tr> |
| <!-- uncomment folling tr iff WildcardURIMatcher is deprecated --> |
| <!--tr> |
| <td>DEPRECATED</td><td>Cocoon 2.0, 2.1</td> |
| </tr--> |
| <tr> |
| <td>SINCE</td><td>Cocoon 2.0</td> |
| </tr> |
| <tr> |
| <td>CACHEABLE</td><td>not applicable</td> |
| </tr> |
| </table> |
| </s1> |
| <s1 title="Description"> |
| <p> |
| The <code>WildcardURIMatcher</code> matches a wildcard pattern against |
| the requested URI. |
| </p> |
| </s1> |
| <s1 title="Usage"> |
| <p> |
| The <code>WildcardURIMatcher</code> 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. |
| </p> |
| <p> |
| The snippet below applies to all requested URIs matching |
| the wildcard pattern <code>page-*.html</code> the same specified pipeline processing. |
| The generator retrieves the xml document having extension <code>.xml</code>, and |
| its basename evaluated from the requested URI path, stripped off the prefix <code>page-</code>. |
| </p> |
| <s2 title="Sitemap pipeline examples"> |
| <p> |
| The snippet below uses the <code>WildcardURIMatcher</code> for matching |
| requested URIs of the form <code>page-*.html</code>. |
| </p> |
| <source><![CDATA[ |
| <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> |
| ... |
| ]]></source> |
| </s2> |
| <s2 title="Sitemap component configuration example"> |
| <p> |
| The <code>WildcardURIMatcher</code> sitemap configuration consists of |
| choosing a name, and specifying the src attribute of the fully qualified name of the |
| WildcardURIMatcher class. |
| </p> |
| <source><![CDATA[ |
| <map:matchers... |
| <map:matcher name="template" |
| src="org.apache.cocoon.matching.WildcardURIMatcher" |
| logger="sitemap.matcher.template" |
| pool-max="32" pool-min="1" pool-grow="4"/> |
| </map:matcher> |
| ... |
| ]]></source> |
| </s2> |
| <s2 title="Configuration"> |
| <p> |
| The <code>WildcardURIMatcher</code> has no extra configuration as already |
| mentioned above. |
| </p> |
| </s2> |
| <s2 title="Setup"> |
| <p> |
| The <code>WildcardURIMatcher</code> gets its wildcard pattern from |
| the pattern attribute. |
| </p> |
| </s2> |
| <s2 title="Effect on Object Model and Sitemap Parameters"> |
| <p> |
| The <code>WildcardURIMatcher</code> accepts wildcard patterns. |
| Wildcard patterns uses following matching algorithm |
| </p> |
| <table> |
| <tr><th>Pattern Token</th><th>Comment</th></tr> |
| <tr><td>**</td><td>Matches zero or more characters including the slash ('/') character</td></tr> |
| <tr><td>*</td><td>Matches zero or more characters excluding the slash ('/') character</td></tr> |
| <tr><td>\ character </td><td>The backslash character is used as escape sequence. |
| Thus \* matches the character asterisk ('*'), and \\ matched the character backslash ('\').</td> |
| </tr> |
| </table> |
| <p> |
| The pattern '**' has higher precedence that two consecutive '*' patterns. |
| </p> |
| <p> |
| If matching succeeds <code>WildcardURIMatcher</code> returns a <code>Map</code> |
| 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 <em>{N}</em>. The N is ordinal number of matched variable part, starting |
| with 0. The expression <code>{0}</code> represents the complete request URI, the |
| expression <code>{1}</code> represents the first matched wildcard value, the expression |
| <code>{2}</code> represents the second, etc. |
| </p> |
| <p> |
| In case of nested matchers, or actions the parent <code>Map</code> entries |
| are referencable by using <code>../</code> prefix. Thus referencing the |
| first wildcard matched value of a parent matcher in a child matcher it |
| is expressed as <code>{../1}</code>. |
| </p> |
| <p> |
| In the snippet above <code>xdocs/{1}.xml</code> is expanded to <code>xdocs/index.xml</code>, |
| if the requested URI was <code>page-index.html</code>. |
| </p> |
| </s2> |
| </s1> |
| <s1 title="Bugs/Caveats"> |
| <p> |
| If a request URI starts with slash ('/'), the slash character is stripped off. |
| </p> |
| </s1> |
| <s1 title="History"> |
| <p> |
| 12-28-02: initial creation |
| </p> |
| </s1> |
| <s1 title="Copyright"> |
| <p> |
| Copyright (C) 1999-2003 The Apache Software Foundation. All rights reserved. |
| </p> |
| </s1> |
| <s1 title="See also"> |
| <p> |
| A general documentation about matchers is available at |
| <link href="../concepts/matchers_selectors.html">Matchers and Selectors</link>. |
| </p> |
| </s1> |
| </body> |
| </document> |
| |
