huber 2002/12/28 14:32:13
Modified: src/documentation/xdocs/userdocs/matchers book.xml
Added: src/documentation/xdocs/userdocs/matchers
wildcarduri-matcher.xml wildcardheader-matcher.xml
template-matcher.xml
Log:
added docs about wildcarduri, and wildcardhost matcher
added template-matcher intended for using when writing new matcher docs
Revision Changes Path
1.2 +2 -0 xml-cocoon2/src/documentation/xdocs/userdocs/matchers/book.xml
Index: book.xml
===================================================================
RCS file: /home/cvs/xml-cocoon2/src/documentation/xdocs/userdocs/matchers/book.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- book.xml 3 Jan 2002 12:31:05 -0000 1.1
+++ book.xml 28 Dec 2002 22:32:13 -0000 1.2
@@ -14,8 +14,10 @@
<menu-item label="Overview" href="matchers.html"/>
</menu>
<menu label="Default">
+ <menu-item label="WildCard URI Matcher" href="wildcarduri-matcher.html"/>
</menu>
<menu label="Core">
+ <menu-item label="WildCard Header Matcher" href="wildcardheader-matcher.html"/>
</menu>
<menu label="Optional">
</menu>
1.1
xml-cocoon2/src/documentation/xdocs/userdocs/matchers/wildcarduri-matcher.xml
Index: wildcarduri-matcher.xml
===================================================================
<?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.1 2002/12/28 22:32:13
huber Exp $
]]>
-->
<document>
<header>
<title>WildcardURI-Matcher in Cocoon</title>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Bernhard Huber" email="[EMAIL PROTECTED]"/>
</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-2002 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>
1.1
xml-cocoon2/src/documentation/xdocs/userdocs/matchers/wildcardheader-matcher.xml
Index: wildcardheader-matcher.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN"
"../../dtd/document-v10.dtd">
<!--
<![CDATA[ CVS Version: $Id: wildcardheader-matcher.xml,v 1.1 2002/12/28 22:32:13
huber Exp $
]]>
-->
<document>
<header>
<title>WildcardHeader-Matcher in Cocoon</title>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Bernhard Huber" email="[EMAIL PROTECTED]"/>
</authors>
<abstract>This document describes the WildcardHeaderMatcher of Cocoon.</abstract>
</header>
<body>
<s1 title="WildcardHeaderMatcher">
<table>
<tr>
<td>NAME</td><td>header-match, referer-match</td>
</tr>
<tr>
<td>WHAT</td><td>The <code>WildcardHeaderMatcher</code> matches a header
value
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 WildcardHeaderMatcher sources live
-->
<td>BLOCK</td><td>Core</td>
</tr>
<tr>
<td>CLASS</td><td>org.apache.cocoon.matching.WildcardHeaderMatcher</td>
</tr>
<!-- uncomment folling tr iff WildcardHeaderMatcher 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>WildcardHeaderMatcher</code> matches a wildcard pattern against a
header value of the request.
</p>
</s1>
<s1 title="Usage">
<p>
The <code>WildcardHeaderMatcher</code> is used to apply the same sitemap
processing
to a group of requested URIs. A requested URI belongs to this group iff
the header value is matched by the specified pattern.
</p>
<p>
The snippet below applies to all requested URIs having a header referer
value matching
the wildcard pattern <code>http://foo.bar:8080/documentation/*.html</code>
the specified pipeline processing.
</p>
<p>
The generator retrieves the xml document having extension <code>.xml</code>,
its basename is the request URI path, stripped off the prefix
<code>page-</code>.
</p>
<s2 title="Sitemap pipeline examples">
<p>
The snippet below uses the <code>WildcardHeaderMatcher</code> for matching
the referer header value.
</p>
<source><![CDATA[
<map:pipelines>
<map:pipeline>
....
<map:match type="referer-match"
pattern=http://foo.bar:8080/documentation/*.html";>
<!-- pipeline processing generator, transformer, serializing
<map:generator src="xdocs/{../1}.xml"/>
<map:transformer src="stylesheet/document2html"/>
<map:parameter name="prev" value="{1}.html"/>
<map:transformer/>
<map:serialize/>
</map:match>
...
</map:pipeline>
...
]]></source>
</s2>
<s2 title="Sitemap component configuration example">
<p>
The <code>WildcardHeaderMatcher</code> sitemap configuration consists of
choosing a name, and specifying the src attribute of the fully qualified
name of the
WildcardHeaderMatcher class.
</p>
<p>
Moreover sub element name <code>header-name</code> specifies the name of
the
header. Its value is matched against the specified pattern.
</p>
<source><![CDATA[
<map:matchers...
<map:matcher name="referer-match"
src="org.apache.cocoon.matching.WildcardHeaderMatcher"
logger="sitemap.matcher.referer-match"
/>
<header-name>referer</header-name>
...
</map:matcher>
...
]]></source>
</s2>
<s2 title="Configuration">
<p>
The <code>WildcardHeaderMatcher</code> is configured by the
subelement <code>header-name</code>, specifying the name of the header
attribute
name.
</p>
</s2>
<s2 title="Setup">
<p>
The <code>WildcardHeaderMatcher</code> gets the wildcard pattern from
its pattern attribute.
</p>
</s2>
<s2 title="Effect on Object Model and Sitemap Parameters">
<p>
See a detailed discussion in
<link href="wildcarduri-matcher.html">WildcardURIMatcher</link>
</p>
</s2>
</s1>
<s1 title="Bugs/Caveats">
<p>
The use of <code>parameter-name</code> instead of <code>header-name</code>
is deprecated.
</p>
</s1>
<s1 title="History">
<p>
12-28-02: initial creation
</p>
</s1>
<s1 title="Copyright">
<p>
Copyright (C) 1999-2002 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>
<p>
For a reference of available header names
see <link href="http://www.ietf.org/rfc/rfc2068.txt";>RFC 2068</link>,
especially
if Cocoon's run time environment is an http servlet environment.
</p>
</s1>
</body>
</document>
1.1
xml-cocoon2/src/documentation/xdocs/userdocs/matchers/template-matcher.xml
Index: template-matcher.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN"
"../../dtd/document-v10.dtd">
<!--
<![CDATA[ CVS Version: $Id: template-matcher.xml,v 1.1 2002/12/28 22:32:13 huber
Exp $
]]>
Using this TemplateMatcher:
* replace TemplateMatcher by the name of the matcher you are describing
* write concrete description
-->
<document>
<header>
<title>Template-Matcher in Cocoon</title>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Your Name" email="your-email"/>
</authors>
<abstract>This document describes the TemplateMatcher of Cocoon.</abstract>
</header>
<body>
<s1 title="TemplateMatcher">
<table>
<tr>
<td>NAME</td><td>template</td>
</tr>
<tr>
<td>WHAT</td><td>The <code>TemplateMatcher</code> component is used
to serve data in a sitemap pipeline.
</td>
</tr>
<tr>
<td>TYPE</td><td>Matcher, Sitemap Component</td>
</tr>
<tr>
<!-- choose Core, the block name, or Scratchpad
depending on where TemplateMatcher sources live
-->
<td>BLOCK</td><td>Core/Block-Name/Scratchpad</td>
</tr>
<tr>
<td>CLASS</td><td>org.apache.cocoon.matching.TemplateMatcher</td>
</tr>
<!-- uncomment folling tr iff TemplateMatcher is deprecated -->
<!--tr>
<td>DEPRECATED</td><td>Cocoon 2.0, 2.1</td>
</tr-->
<tr>
<td>SINCE</td><td>Cocoon X.Y</td>
</tr>
<tr>
<td>CACHEABLE</td><td>not applicable</td>
</tr>
</table>
</s1>
<s1 title="Description">
<p>
A general description of TemplateMatcher
</p>
</s1>
<s1 title="Usage">
<p>
A usage scenario of TemplateMatcher
</p>
<s2 title="Sitemap pipeline examples">
<p></p>
<source><![CDATA[
<map:pipelines>
<map:pipeline>
<map:match pattern="page-*.html">
<map:generator
src="{1}"
>
<!-- option sitemap parameters -->
</map:generator>
</map:match>
</map:pipeline>
...
]]></source>
</s2>
<s2 title="Sitemap component configuration example">
<p></p>
<source><![CDATA[
<map:matchers...
<map:matcher name="template"
src="org.apache.cocoon.matching.TemplateMatcher"
logger="sitemap.matcher.template"
/>
<!-- optional matcher configuration -->
...
</map:matcher>
...
]]></source>
</s2>
<s2 title="Configuration">
<p>
Explain the sitemap matcher configuration, options when declaring template
matcher
</p>
</s2>
<s2 title="Setup">
<p>
Explain the sitemap matcher setup, ie options when using template matcher
</p>
</s2>
<s2 title="Effect on Object Model and Sitemap Parameters">
<p>
</p>
</s2>
</s1>
<s1 title="Bugs/Caveats">
<p>
<!-- Describe limitation, bugs of TemplateMatcher -->
</p>
</s1>
<s1 title="History">
<p>
MM-DD-YY: initial creation
</p>
</s1>
<s1 title="Copyright">
<p>
Copyright (C) 1999-2002 The Apache Software Foundation. All rights reserved.
</p>
</s1>
<s1 title="See also">
<p>
<!-- Links to related components pages. -->
A general documentation about matchers is available at
<link href="../concepts/matchers_selectors.html">Matchers and
Selectors</link>.
</p>
</s1>
</body>
</document>
----------------------------------------------------------------------
In case of troubles, e-mail: [EMAIL PROTECTED]
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
