non-releases/trunk_before_flattening/src/documentation/src/content/xdocs/c21-wildcarduri-matcher/content_en.html - cocoon - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
 <html>
 <head>
 <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
 <title>WildcardURI-Matcher in Cocoon</title>
 <link href="http://purl.org/DC/elements/1.0/" rel="schema.DC">
 <meta content="Bernhard Huber" name="DC.Creator">
 <meta content="This document describes the WildcardURIMatcher of Cocoon." name="DC.Description">
 </head>
 <body>

 <h1>WildcardURIMatcher</h1>

 <table>

 <tr>

 <td colspan="1" rowspan="1">NAME</td><td colspan="1" rowspan="1">wildcard</td>

 </tr>

 <tr>

 <td colspan="1" rowspan="1">WHAT</td><td colspan="1" rowspan="1">The <span class="codefrag">WildcardURIMatcher</span> matches the request URI
             against a wildcard expression..
           </td>

 </tr>

 <tr>

 <td colspan="1" rowspan="1">TYPE</td><td colspan="1" rowspan="1">Matcher, Sitemap Component</td>

 </tr>

 <tr>
           <!-- choose Core, the block name, or Scratchpad
             depending on where WildcardURIMatcher sources live
           -->

 <td colspan="1" rowspan="1">BLOCK</td><td colspan="1" rowspan="1">Core</td>

 </tr>

 <tr>

 <td colspan="1" rowspan="1">CLASS</td><td colspan="1" rowspan="1">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 colspan="1" rowspan="1">SINCE</td><td colspan="1" rowspan="1">Cocoon 2.0</td>

 </tr>

 <tr>

 <td colspan="1" rowspan="1">CACHEABLE</td><td colspan="1" rowspan="1">not applicable</td>

 </tr>

 </table>


 <h1>Description</h1>

 <p>
         The <span class="codefrag">WildcardURIMatcher</span> matches a wildcard pattern against
         the requested URI.
       </p>


 <h1>Usage</h1>

 <p>
         The <span class="codefrag">WildcardURIMatcher</span> 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 <span class="codefrag">page-*.html</span> the same specified pipeline processing.
         The generator retrieves the xml document having extension <span class="codefrag">.xml</span>, and
         its basename evaluated from the requested URI path, stripped off the prefix <span class="codefrag">page-</span>.
       </p>

 <h2>Sitemap pipeline examples</h2>
 <p>
           The snippet below uses the <span class="codefrag">WildcardURIMatcher</span> for matching
           requested URIs of the form <span class="codefrag">page-*.html</span>.
         </p>
 <pre class="code">
 &lt;map:pipelines&gt;
   &lt;map:pipeline&gt;
     &lt;map:match pattern="page-*.html"&gt;
       &lt;!-- pipeline processing generator, transformer, serializing
       &lt;map:generator src="xdocs/{1}.xml"/&gt;
       &lt;map:transformer src="stylesheet/document2html"/&gt;
       &lt;map:serialize/&gt;
     &lt;/map:match&gt;
   &lt;/map:pipeline&gt;
   ...
         </pre>

 <h2>Sitemap component configuration example</h2>
 <p>
           The <span class="codefrag">WildcardURIMatcher</span> sitemap configuration consists of
           choosing a name, and specifying the src attribute of the fully qualified name of the
           WildcardURIMatcher class.
         </p>
 <pre class="code">
 &lt;map:matchers...
   &lt;map:matcher name="template"
     src="org.apache.cocoon.matching.WildcardURIMatcher"
     logger="sitemap.matcher.template"
     pool-max="32"/&gt;
   &lt;/map:matcher&gt;
 ...
 </pre>

 <h2>Configuration</h2>
 <p>
           The <span class="codefrag">WildcardURIMatcher</span> has no extra configuration as already
           mentioned above.
         </p>

 <h2>Setup</h2>
 <p>
           The <span class="codefrag">WildcardURIMatcher</span> gets its wildcard pattern from
           the pattern attribute.
         </p>

 <h2>Effect on Object Model and Sitemap Parameters</h2>
 <p>
           The <span class="codefrag">WildcardURIMatcher</span> accepts wildcard patterns.
           Wildcard patterns uses following matching algorithm
         </p>
 <table>

 <tr>
 <th colspan="1" rowspan="1">Pattern Token</th><th colspan="1" rowspan="1">Comment</th>
 </tr>

 <tr>
 <td colspan="1" rowspan="1">**</td><td colspan="1" rowspan="1">Matches zero or more characters including the slash ('/') character</td>
 </tr>

 <tr>
 <td colspan="1" rowspan="1">*</td><td colspan="1" rowspan="1">Matches zero or more characters excluding the slash ('/') character</td>
 </tr>

 <tr>
 <td colspan="1" rowspan="1">\ character </td><td colspan="1" rowspan="1">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 <span class="codefrag">WildcardURIMatcher</span> returns a <span class="codefrag">Map</span>
           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 <span class="codefrag">{0}</span> represents the complete request URI, the
           expression <span class="codefrag">{1}</span> represents the first matched wildcard value, the expression
           <span class="codefrag">{2}</span> represents the second, etc.
         </p>
 <p>
           In case of nested matchers, or actions the parent <span class="codefrag">Map</span> entries
           are referencable by using <span class="codefrag">../</span> prefix. Thus referencing the
           first wildcard matched value of a parent matcher in a child matcher it
           is expressed as <span class="codefrag">{../1}</span>.
         </p>
 <p>
           In the snippet above <span class="codefrag">xdocs/{1}.xml</span> is expanded to <span class="codefrag">xdocs/index.xml</span>,
           if the requested URI was <span class="codefrag">page-index.html</span>.
         </p>


 <h1>Bugs/Caveats</h1>

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


 <h1>History</h1>

 <p>
         12-28-02: initial creation
       </p>


 <h1>See also</h1>

 <p>
         A general documentation about matchers is available at
         <a href="../concepts/matchers_selectors.html">Matchers and Selectors</a>.
       </p>


 </body>
 </html>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
	<html>
	<head>
	<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
	<title>WildcardURI-Matcher in Cocoon</title>
	<link href="http://purl.org/DC/elements/1.0/" rel="schema.DC">
	<meta content="Bernhard Huber" name="DC.Creator">
	<meta content="This document describes the WildcardURIMatcher of Cocoon." name="DC.Description">
	</head>
	<body>

	<h1>WildcardURIMatcher</h1>

	<table>

	<tr>

	<td colspan="1" rowspan="1">NAME</td><td colspan="1" rowspan="1">wildcard</td>

	</tr>

	<tr>

	<td colspan="1" rowspan="1">WHAT</td><td colspan="1" rowspan="1">The <span class="codefrag">WildcardURIMatcher</span> matches the request URI
	against a wildcard expression..
	</td>

	</tr>

	<tr>

	<td colspan="1" rowspan="1">TYPE</td><td colspan="1" rowspan="1">Matcher, Sitemap Component</td>

	</tr>

	<tr>
	<!-- choose Core, the block name, or Scratchpad
	depending on where WildcardURIMatcher sources live
	-->

	<td colspan="1" rowspan="1">BLOCK</td><td colspan="1" rowspan="1">Core</td>

	</tr>

	<tr>

	<td colspan="1" rowspan="1">CLASS</td><td colspan="1" rowspan="1">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 colspan="1" rowspan="1">SINCE</td><td colspan="1" rowspan="1">Cocoon 2.0</td>

	</tr>

	<tr>

	<td colspan="1" rowspan="1">CACHEABLE</td><td colspan="1" rowspan="1">not applicable</td>

	</tr>

	</table>


	<h1>Description</h1>

	<p>
	The <span class="codefrag">WildcardURIMatcher</span> matches a wildcard pattern against
	the requested URI.
	</p>


	<h1>Usage</h1>

	<p>
	The <span class="codefrag">WildcardURIMatcher</span> 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 <span class="codefrag">page-*.html</span> the same specified pipeline processing.
	The generator retrieves the xml document having extension <span class="codefrag">.xml</span>, and
	its basename evaluated from the requested URI path, stripped off the prefix <span class="codefrag">page-</span>.
	</p>

	<h2>Sitemap pipeline examples</h2>
	<p>
	The snippet below uses the <span class="codefrag">WildcardURIMatcher</span> for matching
	requested URIs of the form <span class="codefrag">page-*.html</span>.
	</p>
	<pre class="code">
	<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>
	...
	</pre>

	<h2>Sitemap component configuration example</h2>
	<p>
	The <span class="codefrag">WildcardURIMatcher</span> sitemap configuration consists of
	choosing a name, and specifying the src attribute of the fully qualified name of the
	WildcardURIMatcher class.
	</p>
	<pre class="code">
	<map:matchers...
	<map:matcher name="template"
	src="org.apache.cocoon.matching.WildcardURIMatcher"
	logger="sitemap.matcher.template"
	pool-max="32"/>
	</map:matcher>
	...
	</pre>

	<h2>Configuration</h2>
	<p>
	The <span class="codefrag">WildcardURIMatcher</span> has no extra configuration as already
	mentioned above.
	</p>

	<h2>Setup</h2>
	<p>
	The <span class="codefrag">WildcardURIMatcher</span> gets its wildcard pattern from
	the pattern attribute.
	</p>

	<h2>Effect on Object Model and Sitemap Parameters</h2>
	<p>
	The <span class="codefrag">WildcardURIMatcher</span> accepts wildcard patterns.
	Wildcard patterns uses following matching algorithm
	</p>
	<table>

	<tr>
	<th colspan="1" rowspan="1">Pattern Token</th><th colspan="1" rowspan="1">Comment</th>
	</tr>

	<tr>
	<td colspan="1" rowspan="1">**</td><td colspan="1" rowspan="1">Matches zero or more characters including the slash ('/') character</td>
	</tr>

	<tr>
	<td colspan="1" rowspan="1">*</td><td colspan="1" rowspan="1">Matches zero or more characters excluding the slash ('/') character</td>
	</tr>

	<tr>
	<td colspan="1" rowspan="1">\ character </td><td colspan="1" rowspan="1">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 <span class="codefrag">WildcardURIMatcher</span> returns a <span class="codefrag">Map</span>
	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 <span class="codefrag">{0}</span> represents the complete request URI, the
	expression <span class="codefrag">{1}</span> represents the first matched wildcard value, the expression
	<span class="codefrag">{2}</span> represents the second, etc.
	</p>
	<p>
	In case of nested matchers, or actions the parent <span class="codefrag">Map</span> entries
	are referencable by using <span class="codefrag">../</span> prefix. Thus referencing the
	first wildcard matched value of a parent matcher in a child matcher it
	is expressed as <span class="codefrag">{../1}</span>.
	</p>
	<p>
	In the snippet above <span class="codefrag">xdocs/{1}.xml</span> is expanded to <span class="codefrag">xdocs/index.xml</span>,
	if the requested URI was <span class="codefrag">page-index.html</span>.
	</p>


	<h1>Bugs/Caveats</h1>

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


	<h1>History</h1>

	<p>
	12-28-02: initial creation
	</p>


	<h1>See also</h1>

	<p>
	A general documentation about matchers is available at
	<a href="../concepts/matchers_selectors.html">Matchers and Selectors</a>.
	</p>


	</body>
	</html>