| <!-- |
| Copyright 1999-2004 The Apache Software Foundation |
| |
| Licensed 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 html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| <html> |
| <head> |
| <title>input</title> |
| |
| <meta http-equiv="content-type" |
| content="text/html; charset=ISO-8859-1"> |
| </head> |
| <body> |
| |
| <h1>InputModules</h1> |
| |
| <h2>Introduction</h2> |
| <p> |
| Input modules are generic components that let one map a key to one or more |
| values. In concept and API, input modules are closest to the <a |
| href="http://java.sun.com/j2se/1.4/docs/api/java/util/Properties.html">java.util.Properties</a> |
| class. An input module has a number of named attributes, each of which has an |
| associated value or values, which will be computed or looked up when requested. |
| </p> |
| <pre> |
| | InputModule | |
| |----------------------------| |
| | PropName | PropValue(s) | |
| |----------------------------| |
| | prop1 | value1 | |
| | prop2 | value2 | |
| | ... | ... | |
| | propn | valuen | |
| +----------------------------+ |
| </pre> |
| <p>Three operations are defined by the <a |
| href="InputModule.html">InputModule</a> interface:</p> |
| <dl> |
| <dt>getAttributeNames</dt> |
| <dd>Retrieve a list of all available attributes (the set <i>prop1, prop2, ..., propn</i>).</dd> |
| <dt>getAttribute</dt> |
| <dd> |
| Retrieve the value of an attribute. For instance, |
| <code>getAttribute(<i>prop1</i>)</code> would return <i>value1</i> |
| </dd> |
| <dt>GetAttributeValues</dt> |
| <dd>Retrieve an Iterator for a list of values for an attribute.</dd> |
| </dl> |
| |
| <h2>Usage</h2> |
| <p> |
| Input modules are used in various places in Cocoon, notably from within the |
| sitemap, XSPs, and matchers.</p> |
| <p> |
| In the sitemap, input modules are made available |
| through a {modulename:attributename} syntax. For instance, if a <a |
| href="RequestParameterModule.html">RequestParameterModule</a> named |
| <code>request-param</code> is defined in cocoon.xconf, then |
| <code>{request-param:user}</code> will in effect be replaced by the value of |
| the <code>user</code> request parameter (e.g. index.html?user=joe). Similarly, |
| a <a href="SystemPropertyModule.html">SystemPropertyModule</a> named |
| <code>system-property</code> would allow |
| <code>{system-property:user.home}</code> to represent user's home directory |
| path. |
| </p> |
| |
| <h2>Configuration</h2> |
| <p> |
| Input modules are declared in cocoon.xconf. There is a section dedicated to |
| input modules:</p> |
| <pre> |
| <input-modules> |
| <component-instance name="global" |
| class="org.apache.cocoon.components.modules.input.GlobalInputModule" |
| logger="core.modules.input"/> |
| <component-instance name="request" |
| class="org.apache.cocoon.components.modules.input.RequestModule" |
| logger="core.modules.input"/> |
| <component-instance name="session" |
| class="org.apache.cocoon.components.modules.input.SessionModule" |
| logger="core.modules.input"/> |
| <component-instance name="request-param" |
| class="org.apache.cocoon.components.modules.input.RequestParameterModule" |
| logger="core.modules.input"/> |
| ... |
| <component-instance name="defaults" |
| class="org.apache.cocoon.components.modules.input.DefaultsModule" |
| logger="core.modules.input"> |
| <values> |
| <skin>defaultSkin</skin> |
| <base-url>http://localhost:8080/cocoon</base-url> |
| </values> |
| </component-instance> |
| <input-modules> |
| </pre> |
| <h3>Static/dynamic configuration</h3> |
| <p> |
| In cocoon.xconf, each input module can take a <em>static</em> configuration. |
| This is made available to the class via the <code>configure()</code> method, |
| called once on startup. In the example above, an Avalon |
| <code>Configuration</code> object representing the <values> node will be |
| passed to the DefaultsModule. |
| </p> |
| <p> |
| In addition, every time an input module is used, a <em>dynamic</em> |
| configuration is passed to it, as well as the current "object model". You can |
| see these in the <a href="InputModule.html">InputModule</a> interface |
| definition for all three methods. This dynamic, per-request configuration will |
| usually <strong>override</strong> the static configuration. This dual |
| static/dynamic configuration makes input modules useful in a wide variety of |
| circumstances. |
| </p> |
| |
| |
| <h2>Meta Modules</h2> |
| <p> |
| So-called "meta" modules are modules that act on other modules. The simplest |
| example of a meta module is the <a |
| href="SimpleMappingMetaModule.html">SimpleMappingMetaModule</a>, which will |
| query another module with a modified version of an attribute name. For |
| instance, if configured with:</p> |
| <pre> |
| <component-instance name="mappingmodule" |
| class="org.apache.cocoon.components.modules.input.SimpleMappingMetaModule" |
| logger="core.modules.mapper"> |
| <input-module name="xmlmodule"/> |
| <prefix>/site/</prefix> |
| <suffix>/@href</suffix> |
| </component-instance> |
| </pre> |
| <p> |
| Then a key <code>foo</code> will cause <code>xmlmodule</code> to be queried for |
| attribute <code>/site/foo/@href</code>, and that value will be returned.</p> |
| <p> |
| Another useful example is <a href="ChainMetaModule.html">ChainMetaModule</a>, |
| which will query a set of input modules until one returns a non-null value for |
| an attribute, providing "fall-back" behaviour. |
| </p> |
| <p> |
| The machinery for meta modules is provided in <a |
| href="AbstractMetaModule.html">AbstractMetaModule</a>. |
| |
| <h2>JXPath use in Input Modules</h2> |
| <p>Many input modules make use of the <a |
| href="http://jakarta.apache.org/commons/jxpath/">JXPath</a> library, which lets |
| one traverse Java object structures with an XPath-like syntax. Support for |
| this is mostly located in the <a |
| href="JXPathMetaModule.html">JXPathMetaModule</a> and <a |
| href="AbstractJXPathModule.html">AbstractJXPathModule</a> superclasses, which |
| should be kept synchronised. |
| </p> |
| |
| <h2>Further Information</h2> |
| <p>The best way to learn what can be done with input modules is by examining |
| the samples that come with the Cocoon application. The main Cocoon |
| documentation and Cocoon Wiki should have further information. |
| </body> |
| </html> |