# ExtendedResourceExistsAction in Cocoon

0.9
Technical document

This document describes the ExtendedResourceExistsAction of Cocoon.

ExtendedResourceExistsAction

NAME | extended-resource-exists
WHAT | The `ExtendedResourceExistsAction` component is used to detect existance of a resource.
TYPE | Action, Sitemap Component
BLOCK | Block-Mail/Scratchpad
CLASS | org.apache.cocoon.acting.ExtendedResourceExistsAction
SINCE | Cocoon 2.1
CACHEABLE | not applicable

Description

The `ExtendedResourceExistsAction` checks the existance of a resource. If the resource exists a sitemap parameter to `true`, otherwise to `false`.

Usage

The `ExtendedResourceExistsAction` is used to control the sitemap processing depending on the existance of a resource.

A use case of `ExtendedResourceExistsAction` is serving default pages, in case of non-existance of a page.

The snippet below uses `ExtendedResourceExistsAction` serving the document `docs/index.html` if the requested document does not exist.

    <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>

Sitemap pipeline examples

The snippet below presents the basic usage of `ExtendedResourceExistsAction`. Note that `ExtendedResourceExistsAction` creates an objectMap having exactly on entry named `resource-exists`. This entry may have value `true`, or `false`.

Thus accessing the wildcard result use `{../1}`, instead of the simple `{1}`.

    <map:match pattern="*.html">
      <map:action type="extended-resource-exists"
        src="docs/{1}.xml">
        ...
      </map:action>
    </map:match>

Sitemap component configuration example

The snippet below confiures the `ExtendedResourceExistsAction` component in the sitemap's components section.

    <map:actions...
      <map:action name="extended-resource-exists"
        src="org.apache.cocoon.acting.ExtendedResourceExistsAction"
        logger="sitemap.action.resource-exists"
      />
      ...
    </map:actions>
    ...

Configuration

The `ExtendedResourceExistsAction` has no configurational options.

Setup

Setting up the `ExtendedResourceExistsAction` needs only specifying the resource by setting the `src` attribute of the `<map:act>` element. This way `ExtendedResourceExistsAction` knows what resource to test for existance.

The `ExtendedResourceExistsAction` accepts optionally a the sitemap parameter `url`, overriding the value presented by the `src` attribute.

Effect on Object Model and Sitemap Parameters

The `ExtendedResourceExistsAction` creates alway an objectMap table, and always sets an `resource-exists` entry in this table.

Bugs/Caveats

The entry name `resource-exists` of the objectMap table entry is fixed, it is not configurable.

The `ExtendedResourceExistsAction` checks the existance of a resource by resolving the name of the resource, and trying to get an `InputStream` of this resource, accessing remote resources may take some time before it is obvious that the resource is, or is not available.

History

01-05-02: initial creation

See also

Cocoon has already an `ResourceExistsAction`. This action creates an objectMap, only in case of resource existance.