cocoon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From hu...@apache.org
Subject cvs commit: xml-cocoon2/src/documentation/xdocs/userdocs/matchers wildcarduri-matcher.xml wildcardheader-matcher.xml template-matcher.xml book.xml
Date Sat, 28 Dec 2002 22:32:13 GMT
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="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-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="huber@apache.org"/>
      </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:     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