| <?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><map:act></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> |
| |
