home *** CD-ROM | disk | FTP | other *** search
/ PC Professionell 2004 December / PCpro_2004_12.ISO / files / webserver / xampp / xampp-cocoon-addon-1.4.9-installer.exe / host-selector.xml < prev    next >
Encoding:
Extensible Markup Language  |  2004-07-12  |  6.6 KB  |  199 lines
  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <!--
  3.   Copyright 1999-2004 The Apache Software Foundation
  4.  
  5.   Licensed under the Apache License, Version 2.0 (the "License");
  6.   you may not use this file except in compliance with the License.
  7.   You may obtain a copy of the License at
  8.  
  9.       http://www.apache.org/licenses/LICENSE-2.0
  10.  
  11.   Unless required by applicable law or agreed to in writing, software
  12.   distributed under the License is distributed on an "AS IS" BASIS,
  13.   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.   See the License for the specific language governing permissions and
  15.   limitations under the License.
  16. -->
  17. <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "document-v10.dtd">
  18.  
  19. <!--
  20.   <![CDATA[ CVS Version: $Id: host-selector.xml,v 1.7 2004/05/08 08:57:58 crossley Exp $ 
  21.   ]]>
  22. -->
  23.  
  24. <document>
  25.   <header>
  26.     <title>Host-Selector in Cocoon</title>
  27.     <version>0.9</version>
  28.     <type>Technical document</type>
  29.     <authors>
  30.       <person name="Bernhard Huber" email="huber@apache.org"/>
  31.     </authors>
  32.     <abstract>This document describes the HostSelector of Cocoon.</abstract>
  33.   </header>
  34.   <body>
  35.     <s1 title="HostSelector">
  36.       <table>
  37.         <tr>
  38.           <td>NAME</td><td>host</td>
  39.         </tr>
  40.         <tr>
  41.           <td>WHAT</td><td>The <code>HostSelector</code> component is used to
  42.             select appropriate sitemap processing depending on <code>Host</code> header
  43.             value.
  44.           </td>
  45.         </tr>
  46.         <tr>
  47.           <td>TYPE</td><td>Selector, Sitemap Component</td>
  48.         </tr>
  49.         <tr>
  50.           <!-- choose Core, the block name, or Scratchpad 
  51.             depending on where HostSelector sources live
  52.           -->
  53.           <td>BLOCK</td><td>Core</td>
  54.         </tr>
  55.         <tr>
  56.           <td>CLASS</td><td>org.apache.cocoon.selection.HostSelector</td>
  57.         </tr>
  58.         <!-- uncomment folling tr if HostSelector is deprecated -->
  59.         <!--tr>
  60.           <td>DEPRECATED</td><td>Cocoon 2.0, 2.1</td>
  61.         </tr-->
  62.         <tr>
  63.           <td>SINCE</td><td>Cocoon 2.0</td>
  64.         </tr>
  65.         <tr>
  66.           <td>CACHEABLE</td><td>not applicable</td>
  67.         </tr>
  68.       </table>
  69.     </s1>
  70.     <s1 title="Description">
  71.       <p>
  72.         The <code>HostSelector</code> tests the <code>Host</code> header field from the 
  73.         request against the test attribute of the selectors when clause.
  74.       </p>
  75.     </s1>
  76.     <s1 title="Usage">
  77.       <p>
  78.         The <code>HostSelector</code> allows to define host specific sitemap
  79.         processing. This way Cocoon can do multi-homed sitemap processing.
  80.       </p>
  81.       <s2 title="Sitemap pipeline examples">
  82.         <p>
  83.           The snippet below uses a <code>HostSelector</code> named <code>host</code>,
  84.           and tests against symbolic host-sites which are configured in the
  85.           <code>host</code> selector section.
  86.         </p>
  87.         <source><![CDATA[
  88. <map:select type="host">
  89.   <map:when test="uk-site">
  90.   ....
  91.   </map:when>
  92.   <map:when test="de-site">
  93.   ...
  94.   </map:when>
  95.   ...
  96.   <map:otherwise>
  97.   ...
  98.   </map:otherwise>
  99. </map:select>
  100.         ]]></source>
  101.       </s2>
  102.       
  103.       <s2 title="Sitemap component configuration example">
  104.         <p>
  105.           The snippet below declares a <code>HostSelector</code>
  106.           defining symbolic host-site names for some host domains.
  107.         </p>
  108.         <source><![CDATA[
  109. <map:selectors>
  110.   <map:selector name="host" 
  111.     src="org.apache.cocoon.selection.HostSelector"
  112.     logger="sitemap.selector.host" 
  113.     
  114.     <host name="uk-site" value="foo.bar.uk"/>
  115.     ...
  116.     <host name="de-site" value="foo.bar.de"/>
  117.     <host name="us-site" value="foo.bar.com"/>
  118.     
  119.   </map:selector>
  120.   ...
  121. </map:selectors>
  122. ]]></source>
  123.       </s2>
  124.       <s2 title="Configuration">
  125.         <p>
  126.           <!-- Explain the sitemap selector configuration, options when declaring host selector -->
  127.           The configuration section of <code>HostSelector</code> specifies
  128.           a mapping from host strings to symbolic host-site names.
  129.         </p>
  130.         <p>
  131.           Each host element specifies a name attribute holding the symbolic host-site name
  132.           used in the test attribute expression. The attribute name contains 
  133.           a matchable substring of some real host header values.
  134.         </p>
  135.         <p>
  136.           It is allowed to specify for a host name more than one entry. This way
  137.           a symbolic host-site name is matched by different host header substrings.
  138.           The snippet belows will yield true for <code>test="central-europe"</code> if 
  139.           the host header contains <code>foo.bar.cz</code>, <code>foo.bar.at</code>, or 
  140.           <code>foo.bar.hu</code>.
  141.         </p>
  142.         <source><![CDATA[
  143. ...
  144.   <host name="central-europe" value="foo.bar.cz"/>
  145.   <host name="central-europe" value="foo.bar.at"/>
  146.   <host name="central-europe" value="foo.bar.uk"/>
  147. ...
  148.         ]]></source>
  149.       </s2>
  150.       <s2 title="Setup">
  151.         <p>
  152.           <!-- Explain the sitemap selector setup, ie options when using host selector -->
  153.           Setting up a <code>HostSelector</code> includes choosing the 
  154.           <code><map:when></code> test expressions and a 
  155.           optional <code><map:otherwise></code> clause.
  156.         </p>
  157.         <p>
  158.           The test attribute of the <code><map:when></code> clause must match
  159.           a host attribute name value. The value of the test attribute in a 
  160.           <code><map:when></code> clause must be declared in a 
  161.           <code>host</code> name attribute.
  162.         </p>
  163.       </s2>
  164.       <s2 title="Effect on Object Model and Sitemap Parameters">
  165.         <p>
  166.           The <code>HostSelector</code> has no side effects on the object model or 
  167.           any sitemap parameters. 
  168.         </p>
  169.       </s2>
  170.     </s1>
  171.     <s1 title="Bugs/Caveats">
  172.       <p>
  173.         The <code>HostSelector</code> adds the response header attribute
  174.         <code>Vary</code> having value <code>Host</code> indicating
  175.         that the response differ for different hosts. This information
  176.         is particularly meaningful for a http-proxy server.
  177.       </p>
  178.     </s1>
  179.     <s1 title="History">
  180.       <p>
  181.         28-12-02: initial creation
  182.       </p>
  183.     </s1>
  184.     <s1 title="See also">
  185.       <p>
  186.         <!-- Links to related components pages. -->
  187.         A general documentation about selectors is available at
  188.         <link href="../concepts/matchers_selectors.html">Matchers and Selectors</link>.
  189.       </p>
  190.       <p>
  191.         For a detailed <code>Host</code> header documentation 
  192.         see <link href="http://www.ietf.org/rfc/rfc2068.txt">RFC 2068</link>, especially
  193.         if Cocoon's run time environment is an http servlet environment. 
  194.       </p>
  195.     </s1>
  196.   </body>
  197. </document>
  198.  
  199.