shannon 02/05/30 10:43:16
Modified: src/documentation/xdocs/userdocs/matchers matchers.xml
Log:
Tightened and clarified the language.
Simplified sentence structure.
Revision Changes Path
1.2 +80 -78
xml-cocoon2/src/documentation/xdocs/userdocs/matchers/matchers.xml
Index: matchers.xml
===================================================================
RCS file:
/home/cvs/xml-cocoon2/src/documentation/xdocs/userdocs/matchers/matchers.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- matchers.xml 3 Jan 2002 12:31:05 -0000 1.1
+++ matchers.xml 30 May 2002 17:43:16 -0000 1.2
@@ -10,13 +10,14 @@
<authors>
<person name="Carsten Ziegeler" email="[EMAIL PROTECTED]"/>
<person name="Gianugo Rabellino" email="[EMAIL PROTECTED]"/>
+ <person name="Diana Shannon, ed." email="[EMAIL PROTECTED]"/>
</authors>
- <abstract>This document describes all available matchers of
Cocoon.</abstract>
+ <abstract>This document describes all of the available matchers of
Cocoon.</abstract>
</header>
<body>
<s1 title="Goal">
<p>
- This document lists all available matchers of Apache Cocoon and
+ This document lists all of the available matchers of Apache Cocoon and
describes their purpose.
See also the concepts document
<link href="../concepts/matchers_selectors.html">Using and Implementing
@@ -25,22 +26,23 @@
</s1>
<s1 title="Overview">
<p>
- Matchers are a core component of Cocoon. These powerful sitemap
- components allow Cocoon to associate a pure
- "virtual" URI space to a given set of instructions that describe
- how to generate, transform and present the requested resource(s) to
- the client.
+ A matcher is a core sitemap component of Cocoon. Matchers allow Cocoon
+ to associate a pure
+ "virtual" URI space with a given set of "instructions"
+ found in a Cocoon sitemap. Sitemap matchers are used to determine the flow
and order
+ of request processing. They typically describe
+ how to generate, transform and present a requested resource(s) to
+ the client. They may also be used to redirect requests to other pipelines
+ or to call other sitemap resources.
</p>
<p>
Cocoon is driven by the client request. A request typically
- contains a URI, some parameters, cookies, and much more. The
- request, along with the Cocoon environment, is the entry
- point to decide what will be the sitemap instructions to be
- used. The mechanism to decide what will be the instruction
- driving the Cocoon process for a given request
- is based on matching a request element against a pattern given
- as a matcher's parameter. If the match operation is successful
- processing starts.
+ contains a URI, some parameters, cookies, and much more. Within
+ the Cocoon environment, the request is evaluated to determine
+ what sitemap instructions to use for processing.
+ More specifically, a given request is matched against a pipeline
+ matcher's pattern attribute. When a match is found,
+ processing of the request begins.
</p>
<p>
As an example, consider the following sitemap snippet:
@@ -62,103 +64,103 @@
]]>
</source>
<p>
- Here the two sitemap entries are mapped to different virtual URIs using
- the default matcher (based on a wildcard intepretation of the request
- URI) in a different way: the first one
- uses an exact match ("body-faq.xml"), meaning that only a Request URI
- that exactly matches the string will result in a successful match. The
- second one uses a wildcard pattern, meaning that every request
- starting with "body-" and ending with ".xml" will satisfy the matcher's
- requirement: thus requesting a resource such as "book-cocoon.xml"
- would turn out in the sitemap matching the request and starting
- the second pipeline.
+ Here the two sitemap entries map request URIs to different virtual URIs using
+ the default wildcard matcher (defined earlier in a matcher component
configuration).
+ The first entry uses an exact match, "body-faq.xml". Only request
URIs
+ composed of this exact string will match this entry. The
+ second sitemap entry uses a wildcard pattern. URI Requests that begin with
+ "body-" and end with ".xml" will meet this matcher's
+ requirement. For example, a URI request for "body-cocoon.xml"
+ would match the second entry.
</p>
</s1>
<s1 title="Order">
<p>
- It's important to understand that Cocoon is based on a "first match"
- approach. The request is matched against the different "map:match"
- entries in the order in which they are specified in the sitemap: as soon
- as a match is successful the pipeline is chosen and started. This means
- that more specific patterns must appear before generic ones: in the
- example above if the two pipelines were in a different order a request
- for "body-faq.xml" would never work properly, since the generic
- "book-**.xml" pattern would be matched first (this is a well known
- concept especially in router and firewall configurations).
+ It's important to understand that Cocoon is based on a "first-match"
+ approach. All requests are matched against the different "map:match"
+ entries in the order in which matchers are specified in the sitemap.
+ As soon
+ as a match is successful, the pipeline processing begins. This means
+ that more specific patterns must appear before more generic ones.
+ If the order of the two pipelines in the above example were reversed,
+ a request for "body-faq.xml" not match "body-faq.xml"
+ but "body-**.xml" because it appears first. (This is a familiar
+ concept, especially in router and firewall configurations.)
</p>
</s1>
<s1 title="Tokenization">
<p>
- Another important feature of matchers is tokenization. Every "variable"
- part of the pattern being matched will be kept in memory by Cocoon for
- further reuse and will be available in the next sitemap instructions
- as a numbered argument. This means that, using once again the previous
- example, when a request URI such as "body-index.xml" comes in and the
- second pipeline is choosen, the string that matches the "**" wildcard,
- containing the value "index", is available in the sitemap as a parameter
- identified by {1}. This string can be used as the parameter for the
- generator which will evaluate the symbol resolving it to the string
- "index" and look for a file named "xdocs/index.html".
+ Another important feature of matchers is tokenization. Every
"variable"
+ part of a matcher pattern will be kept in memory by Cocoon for
+ additional reuse. It remains available within a pipeline match
+ as a numbered argument. Using the previous example, consider a request
+ URI such as "body-index.xml" matched by the second map:match
element.
+ The string "index" which matches the "**" wildcard,
+ is available for reuse by other child elements of map:match. It is
+ identified by the key {1}. This key is used as a parameter for the
+ generator which will first resolve it to the string
+ "index", and then look for a file named
"xdocs/index.html".
</p>
</s1>
<s1 title="Wildcard and regular expressions">
<p>
- Most of Cocoon matchers are built using two different techniques:
+ Most Cocoon matchers are built using two different techniques:
regular expressions and wildcards.
- Regular expressions (or regexps) are a well known and powerful
- system for pattern matching: learning to master them it's outside
- the scope of this document, but there is a lot of documentation
- available on the web regarding this topic.
+ Regular expressions (or regexps) are a well-known and powerful
+ system for pattern matching. Learning how to master them is beyond
+ the scope of this document. However, you will find a lot of documentation
+ on the web regarding this topic.
</p>
<p>
- While being so powerful, regexps can just be overkill for most of
- typical Cocoon use cases where only simple matching operations
- have to be performed. This is why Cocoon offers a simplified
- pattern matching system based on a small set of very simple rules:
+ Although powerful, regexps can be overkill for most
+ typical Cocoon use cases where simple matching operations
+ are performed. This is why Cocoon offers a simplified
+ pattern matching system based on a small set of basic rules.
</p>
<ul>
<li>
- An asterisk ('*') matches zero or more of characters
- up to the occurrence of a '/' character (which is intended as
- a path separator). If a string such as /cocoon/docs/index.html is
- matched against the pattern '/*/*.index.html' the match is <em>not</em>
- succesful: the first asterisk would match only up to the first path
- separator, resulting in the "cocoon" string. Using this technique
- a correct pattern would be '/*/*/*.html'.
+ An asterisk ('*') matches zero or more characters,
+ up to the occurrence of a '/' character (which serves as
+ a path separator). A string, such as "/cocoon/docs/index.html",
+ would <em>not</em>
+ match successfully against the pattern '/*/*.index.html'.
+ The first asterisk matches up to the first path
+ separator only, resulting in the "cocoon" string.
+ A successful matching pattern would be '/*/*/*.html'.
</li>
<li>
- A string made of two asterisks ('**') matches zero or more
- characters, this time including the path separator (the character
- '/'). Using the the example above the string would be matched by
- the /**/*.html' pattern: the double asterisk would match also the
- path separator and would resolve in the "cocoon/docs" string.
+ A string containing two asterisks ('**') matches zero or more
+ characters. This could include the path separator '/'.
+ In this case, "/cocoon/docs/index.html" would successfully
+ match the '/**/*.html' pattern. The double asterisk, including the
+ path separator, would match the "cocoon/docs" string.
</li>
<li>
- As with regexps the backslash character ('\') is used as an
+ As with regexps, the backslash character ('\') is used to indicate an
escape sequence. The string '\*' will match an actual asterisk
while a double backslash ('\\') will match the character '\'. A
- pattern such as "**/a-\*-is-born.html" would match only strings
- such as "documents/movies/a-*-is-born.html" or
- 'a/very/long/path/a-*-is-born.html'. It would <em>not</em> match
- a string such as 'docs/a-star-is-born.html'.
+ pattern such as "**/a-\*-is-born.html" would match strings
+ such as "documents/movies/a-*-is-born.html" or
+ "a/very/long/path/a-*-is-born.html". It would <em>not</em> match
+ the string "docs/a-star-is-born.html".
</li>
</ul>
</s1>
- <s1 title="The Matchers in Cocoon">
+ <s1 title="Matchers in Cocoon">
<ul>
- <li><strong>WildCard URI matcher</strong>(The default
matcher): matches the URI against a wildcard pattern</li>
+ <li><strong>WildCard URI matcher</strong>(The default
matcher): matches the URI against a wildcard pattern.</li>
<li><strong>Regexp URI matcher:</strong>
- matches the URI against a fully blown regular expression</li>
+ matches the URI against a full-blown regular expression</li>
<li><strong>Request parameter
matcher:</strong> matches a request parameters given as a pattern. If
- the parameter exists, its value is available for later substitution
+ the parameter exists, its value is available for later substitution.
</li>
<li><strong>Wildcard request parameter
matcher:</strong> matches a wildcard
- given as a pattern against the <strong>value</strong> of the configured
- parameter
+ given as a pattern against the <strong>value</strong> of a configured
+ parameter.
</li>
- <li><strong>Wildcard session parameter
matcher</strong>: same as the
- request parameter, but it matches a session parameter</li>
+ <li><strong>Wildcard session parameter
matcher</strong>: similar to the
+ Wildcard request parameter matcher, but it matches a session
parameter.</li>
</ul>
</s1>
</body>
----------------------------------------------------------------------
In case of troubles, e-mail: [EMAIL PROTECTED]
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
