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 / extendedresourceexists-action.xml < prev    next >
Encoding:
Extensible Markup Language  |  2004-07-12  |  6.6 KB  |  196 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" "../../dtd/document-v10.dtd">
  18.  
  19. <document>
  20.   <header>
  21.     <title>ExtendedResourceExistsAction in Cocoon</title>
  22.     <version>0.9</version>
  23.     <type>Technical document</type>
  24.     <authors>
  25.       <person name="Bernhard Huber" email="huber.at.apache.org"/>
  26.     </authors>
  27.     <abstract>This document describes the ExtendedResourceExistsAction of Cocoon.</abstract>
  28.   </header>
  29.   <body>
  30.     <s1 title="ExtendedResourceExistsAction">
  31.       <table>
  32.         <tr>
  33.           <td>NAME</td><td>extended-resource-exists</td>
  34.         </tr>
  35.         <tr>
  36.           <td>WHAT</td><td>The <code>ExtendedResourceExistsAction</code> component is used 
  37.             to detect existance of a resource.
  38.           </td>
  39.         </tr>
  40.         <tr>
  41.           <td>TYPE</td><td>Action, Sitemap Component</td>
  42.         </tr>
  43.         <tr>
  44.           <!-- choose Core, the block name, or Scratchpad 
  45.             depending on where ExtendedResourceExistsAction sources live
  46.           -->
  47.           <td>BLOCK</td><td>Block-Mail/Scratchpad</td>
  48.         </tr>
  49.         <tr>
  50.           <td>CLASS</td><td>org.apache.cocoon.acting.ExtendedResourceExistsAction</td>
  51.         </tr>
  52.         <!-- uncomment folling tr iff ExtendedResourceExistsAction is deprecated -->
  53.         <!--tr>
  54.           <td>DEPRECATED</td><td>Cocoon 2.0, 2.1</td>
  55.         </tr-->
  56.         <tr>
  57.           <td>SINCE</td><td>Cocoon 2.1</td>
  58.         </tr>
  59.         <tr>
  60.           <td>CACHEABLE</td><td>not applicable</td>
  61.         </tr>
  62.       </table>
  63.     </s1>
  64.     <s1 title="Description">
  65.       <p>
  66.         The <code>ExtendedResourceExistsAction</code> checks the existance of a resource.
  67.         If the resource exists a sitemap parameter to <code>true</code>,
  68.         otherwise to <code>false</code>.
  69.       </p>
  70.     </s1>
  71.     <s1 title="Usage">
  72.       <p>
  73.         The <code>ExtendedResourceExistsAction</code> is used to control the sitemap
  74.         processing depending on the existance of a resource.
  75.       </p>
  76.       <p>
  77.         A use case of <code>ExtendedResourceExistsAction</code> is serving default
  78.         pages, in case of non-existance of a page.
  79.       </p>
  80.       <p>
  81.         The snippet below uses <code>ExtendedResourceExistsAction</code>
  82.         serving the document <code>docs/index.html</code> if the
  83.         requested document does not exist.
  84.       </p>
  85.       <source><![CDATA[
  86. <map:match pattern="*.html">
  87.   <map:act type="extended-resource-exists"
  88.     src="docs/{1}.html"
  89.     <map:select type="parameter">
  90.       <map:parameter name="parameter-selector-test" value="{resource-exists}"/>
  91.       <map:when test="true">
  92.         <!-- resource exists, access the matched URI via {../1} -->
  93.         <map:generate src="docs/{../1}.xml"/>
  94.       </map:when>
  95.       <map:otherwise>
  96.         <!-- resource does not exist, serve default page -->
  97.         <map:generate src="docs/index.xml"/>
  98.       </map:otherwise>
  99.     </map:select>
  100.   >
  101.     ...
  102.   </map:act>
  103. </map:match>
  104.       ]]></source>
  105.  
  106.       <s2 title="Sitemap pipeline examples">
  107.         <p>
  108.           The snippet below presents the basic usage of <code>ExtendedResourceExistsAction</code>.
  109.           Note that <code>ExtendedResourceExistsAction</code> creates an 
  110.           objectMap having exactly on entry named <code>resource-exists</code>. This entry
  111.           may have value <code>true</code>, or <code>false</code>.
  112.         </p>
  113.         <p>
  114.           Thus accessing the wildcard result use <code>{../1}</code>, instead of the
  115.           simple <code>{1}</code>.
  116.         </p>
  117.         <source><![CDATA[
  118. <map:match pattern="*.html">
  119.   <map:action type="extended-resource-exists" 
  120.     src="docs/{1}.xml">
  121.     ...
  122.   </map:action>
  123. </map:match>
  124.         ]]></source>
  125.       </s2>
  126.       
  127.       <s2 title="Sitemap component configuration example">
  128.         <p>
  129.           The snippet below confiures the <code>ExtendedResourceExistsAction</code>
  130.           component in the sitemap's components section.
  131.         </p>
  132.         <source><![CDATA[
  133. <map:actions...
  134.   <map:action name="extended-resource-exists" 
  135.     src="org.apache.cocoon.acting.ExtendedResourceExistsAction"
  136.     logger="sitemap.action.resource-exists" 
  137.   />
  138.   ...
  139. </map:actions>
  140. ...
  141. ]]></source>
  142.       </s2>
  143.       <s2 title="Configuration">
  144.         <p>
  145.           The <code>ExtendedResourceExistsAction</code> has no configurational options.
  146.         </p>
  147.       </s2>
  148.       <s2 title="Setup">
  149.         <p>
  150.           Setting up the <code>ExtendedResourceExistsAction</code> needs
  151.           only specifying the resource by setting the <code>src</code> attribute
  152.           of the <code><map:act></code> element. This way 
  153.           <code>ExtendedResourceExistsAction</code> knows what resource to test
  154.           for existance.
  155.         </p>
  156.         <p>
  157.           The <code>ExtendedResourceExistsAction</code> accepts optionally a the
  158.           sitemap parameter <code>url</code>, overriding the value presented
  159.           by the <code>src</code> attribute.
  160.         </p>
  161.       </s2>
  162.       <s2 title="Effect on Object Model and Sitemap Parameters">
  163.         <p>
  164.           The <code>ExtendedResourceExistsAction</code> creates alway an
  165.           objectMap table, and always sets an <code>resource-exists</code>
  166.           entry in this table.
  167.         </p>
  168.       </s2>
  169.     </s1>
  170.     <s1 title="Bugs/Caveats">
  171.       <p>
  172.         The entry name <code>resource-exists</code> of the objectMap table entry
  173.         is fixed, it is not configurable.
  174.       </p>
  175.       <p>
  176.         The <code>ExtendedResourceExistsAction</code> checks the existance of a resource
  177.         by resolving the name of the resource, and trying to get an <code>InputStream</code>
  178.         of this resource, accessing remote resources may take some time before
  179.         it is obvious that the resource is, or is not available.
  180.       </p>
  181.     </s1>
  182.     <s1 title="History">
  183.       <p>
  184.         01-05-02: initial creation
  185.       </p>
  186.     </s1>
  187.     <s1 title="See also">
  188.       <p>
  189.         Cocoon has already an <code>ResourceExistsAction</code>. This action
  190.         creates an objectMap, only in case of resource existance.
  191.       </p>
  192.     </s1>
  193.   </body>
  194. </document>
  195.  
  196.