cocoon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From shan...@apache.org
Subject cvs commit: xml-cocoon2/src/documentation/xdocs/userdocs/matchers matchers.xml
Date Thu, 30 May 2002 17:43:16 GMT
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="cziegeler@apache.org"/>
   			<person name="Gianugo Rabellino" email="gianugo@rabellino.it"/>
  +			<person name="Diana Shannon, ed." email="shannon@apache.org"/>
   		 </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
  +      &quot;virtual&quot; URI space with a given set of &quot;instructions&quot;
  +      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, &quot;body-faq.xml&quot;. 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
  +      &quot;body-&quot; and end with &quot;.xml&quot; will meet this matcher's
  +      requirement. For example, a URI request for &quot;body-cocoon.xml&quot; 
  +      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 &quot;body-faq.xml&quot;
  +       but &quot;body-**.xml&quot; 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 &quot;variable&quot;
  +       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 &quot;body-index.xml&quot; matched by the second map:match element.
  +       The string &quot;index&quot; 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 
  +       &quot;index&quot;, and then look for a file named &quot;xdocs/index.html&quot;.
 
          </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 &quot;/cocoon/docs/index.html&quot;,

  +        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 &quot;cocoon&quot; 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, &quot;/cocoon/docs/index.html&quot; would successfully
  +        match the '/**/*.html' pattern. The double asterisk, including the
  +        path separator, would match the &quot;cocoon/docs&quot; 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 &quot;documents/movies/a-*-is-born.html&quot; or 
  +        &quot;a/very/long/path/a-*-is-born.html&quot;. It would <em>not</em>
match
  +        the string &quot;docs/a-star-is-born.html&quot;.
           </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:     webmaster@xml.apache.org
To unsubscribe, e-mail:          cocoon-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: cocoon-cvs-help@xml.apache.org


Mime
View raw message