<?xml version="1.0" encoding="UTF-8"?>
<!--
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You under the Apache License, Version 2.0
  (the "License"); you may not use this file except in compliance with
  the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">

<document>
  <header>
    <title>ExtendedResourceExistsAction in Cocoon</title>
    <version>0.9</version>
    <type>Technical document</type>
    <authors>
      <person name="Bernhard Huber" email="huber.at.apache.org"/>
    </authors>
    <abstract>This document describes the ExtendedResourceExistsAction of Cocoon.</abstract>
  </header>
  <body>
    <s1 title="ExtendedResourceExistsAction">
      <table>
        <tr>
          <td>NAME</td><td>extended-resource-exists</td>
        </tr>
        <tr>
          <td>WHAT</td><td>The <code>ExtendedResourceExistsAction</code> component is used 
            to detect existance of a resource.
          </td>
        </tr>
        <tr>
          <td>TYPE</td><td>Action, Sitemap Component</td>
        </tr>
        <tr>
          <!-- choose Core, the block name, or Scratchpad 
            depending on where ExtendedResourceExistsAction sources live
          -->
          <td>BLOCK</td><td>Block-Mail/Scratchpad</td>
        </tr>
        <tr>
          <td>CLASS</td><td>org.apache.cocoon.acting.ExtendedResourceExistsAction</td>
        </tr>
        <!-- uncomment folling tr iff ExtendedResourceExistsAction is deprecated -->
        <!--tr>
          <td>DEPRECATED</td><td>Cocoon 2.0, 2.1</td>
        </tr-->
        <tr>
          <td>SINCE</td><td>Cocoon 2.1</td>
        </tr>
        <tr>
          <td>CACHEABLE</td><td>not applicable</td>
        </tr>
      </table>
    </s1>
    <s1 title="Description">
      <p>
        The <code>ExtendedResourceExistsAction</code> checks the existance of a resource.
        If the resource exists a sitemap parameter to <code>true</code>,
        otherwise to <code>false</code>.
      </p>
    </s1>
    <s1 title="Usage">
      <p>
        The <code>ExtendedResourceExistsAction</code> is used to control the sitemap
        processing depending on the existance of a resource.
      </p>
      <p>
        A use case of <code>ExtendedResourceExistsAction</code> is serving default
        pages, in case of non-existance of a page.
      </p>
      <p>
        The snippet below uses <code>ExtendedResourceExistsAction</code>
        serving the document <code>docs/index.html</code> if the
        requested document does not exist.
      </p>
      <source><![CDATA[
<map:match pattern="*.html">
  <map:act type="extended-resource-exists"
    src="docs/{1}.html"
    <map:select type="parameter">
      <map:parameter name="parameter-selector-test" value="{resource-exists}"/>
      <map:when test="true">
        <!-- resource exists, access the matched URI via {../1} -->
        <map:generate src="docs/{../1}.xml"/>
      </map:when>
      <map:otherwise>
        <!-- resource does not exist, serve default page -->
        <map:generate src="docs/index.xml"/>
      </map:otherwise>
    </map:select>
  >
    ...
  </map:act>
</map:match>
      ]]></source>

      <s2 title="Sitemap pipeline examples">
        <p>
          The snippet below presents the basic usage of <code>ExtendedResourceExistsAction</code>.
          Note that <code>ExtendedResourceExistsAction</code> creates an 
          objectMap having exactly on entry named <code>resource-exists</code>. This entry
          may have value <code>true</code>, or <code>false</code>.
        </p>
        <p>
          Thus accessing the wildcard result use <code>{../1}</code>, instead of the
          simple <code>{1}</code>.
        </p>
        <source><![CDATA[
<map:match pattern="*.html">
  <map:action type="extended-resource-exists" 
    src="docs/{1}.xml">
    ...
  </map:action>
</map:match>
        ]]></source>
      </s2>
      
      <s2 title="Sitemap component configuration example">
        <p>
          The snippet below confiures the <code>ExtendedResourceExistsAction</code>
          component in the sitemap's components section.
        </p>
        <source><![CDATA[
<map:actions...
  <map:action name="extended-resource-exists" 
    src="org.apache.cocoon.acting.ExtendedResourceExistsAction"
    logger="sitemap.action.resource-exists" 
  />
  ...
</map:actions>
...
]]></source>
      </s2>
      <s2 title="Configuration">
        <p>
          The <code>ExtendedResourceExistsAction</code> has no configurational options.
        </p>
      </s2>
      <s2 title="Setup">
        <p>
          Setting up the <code>ExtendedResourceExistsAction</code> needs
          only specifying the resource by setting the <code>src</code> attribute
          of the <code>&lt;map:act&gt;</code> element. This way 
          <code>ExtendedResourceExistsAction</code> knows what resource to test
          for existance.
        </p>
        <p>
          The <code>ExtendedResourceExistsAction</code> accepts optionally a the
          sitemap parameter <code>url</code>, overriding the value presented
          by the <code>src</code> attribute.
        </p>
      </s2>
      <s2 title="Effect on Object Model and Sitemap Parameters">
        <p>
          The <code>ExtendedResourceExistsAction</code> creates alway an
          objectMap table, and always sets an <code>resource-exists</code>
          entry in this table.
        </p>
      </s2>
    </s1>
    <s1 title="Bugs/Caveats">
      <p>
        The entry name <code>resource-exists</code> of the objectMap table entry
        is fixed, it is not configurable.
      </p>
      <p>
        The <code>ExtendedResourceExistsAction</code> checks the existance of a resource
        by resolving the name of the resource, and trying to get an <code>InputStream</code>
        of this resource, accessing remote resources may take some time before
        it is obvious that the resource is, or is not available.
      </p>
    </s1>
    <s1 title="History">
      <p>
        01-05-02: initial creation
      </p>
    </s1>
    <s1 title="See also">
      <p>
        Cocoon has already an <code>ResourceExistsAction</code>. This action
        creates an objectMap, only in case of resource existance.
      </p>
    </s1>
  </body>
</document>

