Package org.apache.cocoon.components.modules.input

InputModules Introduction Input modules are generic components that let one map a key to one or more values.

See:
Description

Interface Summary

InputModule

InputModule specifies an interface for components that provide access to individual attributes e.g. request parameters, request attributes, session attributes &c.

input-module Configuration and name of input module used for the selection.

Class Summary

AbstractInputModule	AbstractInputModule gives you the infrastructure for easily deploying more InputModules.
AbstractJXPathModule	JXPathModule allows to access properties of any object in generic way.
AbstractMetaModule	AbstractMetaModule gives you the infrastructure for easily deploying more "meta" InputModules i.e.
BaseLinkModule	BaseLinkModule returns a relative link (..
ChainMetaModule	This modules allows to "chain" several other modules.
CollectionMetaModule	Constructs an array of values suitable for a JDBC collection type from parameters obtained from another input module.
ContextPathModule	ContextPathModule provides a real filesystem path for a virtual context-relative path.
CookieModule	Input module for cookies.
DateInputModule	DateInputModule returns current date, optionally formated as string.
DateMetaInputModule	Parses a date string according to a given format and returns a date object.
DefaultsMetaModule	Deprecated. Use DefaultsModule instead; this is not a 'meta' module and is thus misnamed.
DefaultsModule	Set a number of constants.
DigestMetaModule	Meta module that obtains values from other module and returns message digest of value.
FlowAttributeModule	FlowAttributeModule provides access to the flow business object properties.
FlowContinuationModule	FlowContinuationModule provides access to the flow web continuation object.
GlobalInputModule	Deprecated. This module will be replaced by a better version in 2.2.
HeaderAttributeModule	HeaderAttributeModule accesses request header attributes.
InputModuleHelper
JXPathHelper
JXPathHelperConfiguration
JXPathMetaModule	JXPathModule allows to access properties of any object in generic way.
LocateResource	Locate a resource in a resource tree.
MapMetaModule	Meta module that obtains an Object from another module, assumes that this Object implements the java.util.Map interface, and gives access to the map contents.
ModuleHolder
NamingInputModule	NamingInputModule accesses values stored in the JNDI context.
NullInputModule	NullInputModule returns a null object.
PortletURLModule	Input module to be used in together with LinkRewriterTransformer in JSR-168 (Portlet) environment.
ProjectPathModule	ProjectPathModule provides relative and absolute paths with regards to the root of a project.
PropertiesFileModule	Input module for accessing properties in a properties file.
RandomNumberModule	RandomNumberModule returns a random number as a string.
RawRequestParameterModule	RawRequestParameterModule accesses request parameters without decoding to the specified form-encoding or casting.
RealPathModule	RealPathModule provides a real filesystem path for a virtual context-relative path.
RequestAttributeModule	RequestAttributeModule accesses request attributes.
RequestModule	RequestModule provides access to Request object properties.
RequestParameterModule	RequestParameterModule accesses request parameters.
RequestURIModule	RequestURIModule accesses the request URI.
SelectMetaInputModule	Configuration
SessionAttributeModule	SessionAttributeModule accesses session attributes.
SessionModule	SessionModule provides access to Session object properties.
SimpleMappingMetaModule	Meta module that obtains values from an other module and by replacing the requested attribute name with another name.
SimpleMappingMetaModule.Mapping
SitemapVariableHolder	Deprecated. This component will be replaced by a better version in 2.2.
StringConstantModule	StringConstantModule returns a constant string.
SystemPropertyModule	SystemPropertyModule is an JXPath based InputModule implementation that provides access to system properties.
URLDecodeModule	This module provides functionality for converting a String from the application/x-www-form-urlencoded MIME format.
URLEncodeModule	This module provides functionality for converting a String to the application/x-www-form-urlencoded MIME format.
XMLFileModule	This module provides an Input Module interface to any XML document, by using XPath expressions as attribute keys.
XMLFileModule.DocumentHelper	Takes care of (re-)loading and caching of sources.
XMLMetaModule	Meta module that obtains values from other module and returns all parameters as XML.
XPathXMLFileModule	This module provides an Input Module interface to any XML document, by using XPath expressions as attribute keys.

Package org.apache.cocoon.components.modules.input Description

InputModules

Introduction

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 java.util.Properties 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.

    |       InputModule          |
    |----------------------------|
    | PropName   | PropValue(s)  |
    |----------------------------|
    | prop1      | value1        |
    | prop2      | value2        |
    | ...        | ...           |
    | propn      | valuen        |
    +----------------------------+

Three operations are defined by the InputModule interface:

getAttributeNames

Retrieve a list of all available attributes (the set prop1, prop2, ..., propn).

getAttribute

Retrieve the value of an attribute. For instance, getAttribute(prop1) would return value1

GetAttributeValues

Retrieve an Iterator for a list of values for an attribute.

Usage

Input modules are used in various places in Cocoon, notably from within the sitemap, XSPs, and matchers.

In the sitemap, input modules are made available through a {modulename:attributename} syntax. For instance, if a RequestParameterModule named request-param is defined in cocoon.xconf, then {request-param:user} will in effect be replaced by the value of the user request parameter (e.g. index.html?user=joe). Similarly, a SystemPropertyModule named system-property would allow {system-property:user.home} to represent user's home directory path.

Configuration

Input modules are declared in cocoon.xconf. There is a section dedicated to input modules:

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

Static/dynamic configuration

In cocoon.xconf, each input module can take a static configuration. This is made available to the class via the configure() method, called once on startup. In the example above, an Avalon Configuration object representing the <values> node will be passed to the DefaultsModule.

In addition, every time an input module is used, a dynamic configuration is passed to it, as well as the current "object model". You can see these in the InputModule interface definition for all three methods. This dynamic, per-request configuration will usually override the static configuration. This dual static/dynamic configuration makes input modules useful in a wide variety of circumstances.

Meta Modules

So-called "meta" modules are modules that act on other modules. The simplest example of a meta module is the SimpleMappingMetaModule, which will query another module with a modified version of an attribute name. For instance, if configured with:

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

Then a key foo will cause xmlmodule to be queried for attribute /site/foo/@href, and that value will be returned.

Another useful example is ChainMetaModule, which will query a set of input modules until one returns a non-null value for an attribute, providing "fall-back" behaviour.

The machinery for meta modules is provided in AbstractMetaModule.

JXPath use in Input Modules

Many input modules make use of the JXPath library, which lets one traverse Java object structures with an XPath-like syntax. Support for this is mostly located in the JXPathMetaModule and AbstractJXPathModule superclasses, which should be kept synchronised.

Further Information

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.