apache > cocoon
 

Input Modules Reference

A concise reference to Cocoon's InputModules.

Introduction

This is meant to be a concise reference to Cocoon's InputModules, what they do, and how to use them. InputModules are available in Cocoon 2.0.4 and above. Many descriptions are taken directly from the respective modules' source code, or from trial and error experimentation.

Note
See also: the InputModules Wiki Page.

Modules Reference

AbstractInputModule

AbstractInputModule gives you the infrastructure for easily deploying more InputModules.

AbstractJXPathModule

Note
The following is the same as described in the JXPathMetaModule, but the JXPathMetaModule actually doesn't inherit from AbstractJXPathModule.

JXPathModule allows to access properties of any object in generic way. JXPath provides APIs for the traversal of graphs of JavaBeans, DOM and other types of objects using the XPath syntax. JXPathMetaModule is based on this class and duplicates the code since multiple inheritance is not possible. Please keep both classes in sync.

Configuration example:

<lenient>false</lenient>

When set to true, non-existing attributes return null, when set to false, an exception is thrown. Default is true.

<parameter>foo</parameter>

When set overrides attribute name passed to module.

<function name="java.lang.String" prefix="str"/>

Imports the class "String" as extension class to the JXPathContext using the prefix "str". Thus "str:length(xpath)" would apply the method "length" to the string object obtained from the xpath expression. Please note that the class needs to be fully qualified.

<package name="java.util" prefix="util"/>

Imports all classes in the package "java.util" as extension classes to the JXPathContext using the prefix "util". Thus "util:Date.new()" would create a new java.util.Date object.

AbstractMetaModule

AbstractMetaModule gives you the infrastructure for easily deploying more "meta" InputModules i.e. InputModules that are composed of other InputModules. In order to get at the Logger, use getLogger().

BaseLinkModule

BaseLinkModule returns a relative link (../, ../../ etc) to the base of the current request or sitemap URI. For instance, if called within a <map:match pattern="a/b/c.xsp"> pipeline, {baselink:SitemapBaseLink} would evaluate to ../../.

ChainMetaModule

This modules allows to "chain" several other modules. If a module returns "null" as attribute value, the next module in the chain is queried until either a value can be obtained or the end of the chain is reached.

A typical example would be to "chain" request parameters, session attributes, and constants in this order. This way, an application could have a default skin that could be overridden by a user in her/his profile stored in the session. In addition, the user could request a different skin through passing a request parameter.

Usage:

Any number of <input-module/> blocks may appear in the component configuration. The @name attribute is used as the name of the requested input module. The complete <input-module/> block is passed at run-time to the module and thus can contain any configuration data for that particular module.

Configuration:

It can be controlled whether it returns a flat or a deep view, i.e. whether only values from the first module are returned if non-null or they are merged with values from other modules <all-values>true</all-values>. The same is possible for the attribute names (<all-names/>). In addition, empty strings could be treated the same as null values (<empty-as-null/>).

ContextPathModule

ContextRealPathModule provides a real filesystem path for a virtual context-relative path. If this mapping cannot be performed (e.g. Cocoon is running in a .war file), null will be returned. Compared to the RealPathModule this module is able to provide the "real" absolute path even if the application is mounted outside the webapp tree of Cocoon.

Note: the primary use for this is to support external code that wants a filesystem path. For example, The FOP 0.20.x serializer doesn't like relative image paths, and doesn't understand Cocoon URLs (context:, cocoon: etc). So we pass the *2fo.xsl stylesheet a real filesystem path to where we keep our images:

A absolute path argument like {contextrealpath:/resources} will be resolved from the root context path (ie. COCOON_HOME/build/webapp) whereas a relative path attribute like {contextrealpath:./resources} will be resolved from the location of the sitemap that uses it. If that sitemap is mounted outside the usual COCOON_HOME/build/webapp the path resolved with this modules points to the correct location.

<map:transform src="skins/%7Bforrest:skin%7D/xslt/fo/document2fo.xsl">
    <map:parameter name="basedir" value="{contextrealpath:resources}/">
 </map:parameter>

 And then prepend this to all image paths:
  ...
  <xsl:param name="basedir" select="''">
  ...
  <xsl:template match="img">
      <xsl:variable name="imgpath" select="concat($basedir, @src)">
      <fo:external-graphic src="%7B$imgpath%7D" .=""></fo:external-graphic>
  </xsl:variable></xsl:template></xsl:param></map:transform>

CollectionMetaModule

Constructs an array of values suitable for a JDBC collection type from parameters obtained from another input module. Application is not limited to JDBC collections but can be used wherever similar named attributes shall be collected to an array of a given type. Currently, long, int, and string are known, more to come.

Global and Local Configuration:

Fixme
Finish the reference for this Module.

CookieModule

This module returns the value of the named HTTP cookie.

Example Pipeline Fragment:

<map:match pattern="foo.html">
  <map:generate type="file" src="documents/{cookie:user-language}/foo.xml"/>
  <map:transform src="stylesheets/foo2html.xsl"/>
  <map:serialize/>
</map:match>

DateInputModule

This module returns the current date, optionally formatted as string. Format given through attribute "format" of configuration root node or nested <format/> tag on module declaration.

Note
The 'format' attribute doesn't seem to work. Nested <format/> tags work fine.
Note
See also: Java Date Format.

DateMetaInputModule

Parses a date string according to a given format and returns a date object. Configuration options: element "format" to hold a SimpleDateFormat format string, child element "input-module" holds InputModule to obtain the string from.

DefaultsModule

Set a number of constants. To override the values with input from another module, combine this one with the ChainMetaModule and an arbitrary number of other modules. <values> <skin>myskin</skin> <base>baseurl</base> ... </values>

DigestMetaModule

Meta module that obtains values from other module and returns message digest of value. Very useful for storing and checking passwords. Input module configured through nested element "input-module", message digest algorithm, security provider, salt, and URL encoded output configurable through elements "algorithm", "provider", "salt", "encode". Defaults are "sha", null, "salt", and "false". Available value for encode are "none" (returns byte[]), "string" (return hash as string), "url" (returns url encoded string), "hex" (returns string of hex values).

FlowAttributeModule

FlowAttributeModule provides access to the flow business object properties. To get access to the properties use XPath syntax. If requested object is not found then an exception will be thrown.

FlowContinuationModule

FlowContinuationModule provides access to the flow web continuation object. To get access to the properties use XPath syntax. If requested object is not found then an exception will be thrown.

GlobalInputModule

This module allows you to access "global" variables which are defined in a sitemap's pipelines definition.

cocoon.xconf usage:

<input-modules>
  ...
  <component-instance 
     class="org.apache.cocoon.components.modules.input.GlobalInputModule" 
     logger="core.modules.input" 
     name="global"/>
  ...
</input-modules>

Sitemap Usage:

<map:component-configurations>
  <global-variables>
      <doc>doc.xml</doc>
  </global-variables>
</map:component-configurations>

Example Pipeline Fragment:

<map:match pattern="foo">
  <map:generate type="file" src="documents/{global:doc}"/>
  <map:transform src="stylesheets/foo2html.xsl"/>
  <map:serialize/>
</map:match>

HeaderAttributeModule

HeaderAttributeModule accesses request header attributes. If the attribute name contains an asterisk "*" this is considered a wildcard and all attributes that would match this wildcard are considered to be part of an array of that name for getAttributeValues. Only one "*" is allowed.

JXPathMetaModule

JXPathModule allows to access properties of any object in generic way. JXPath provides APIs for the traversal of graphs of JavaBeans, DOM and other types of objects using the XPath syntax. This is based on the AbstractJXPathModule and duplicates the code since multiple inheritance is not possible. Please keep both classes in sync.

Configuration example:

<lenient>false</lenient>

When set to true, non-existing attributes return null, when set to false, an exception is thrown. Default is true.

<parameter>false</parameter>

Attribute name to be used instead of passed attribute name.

<from-parameter>false</from-parameter>

Attribute name to pass to configured input module

<input-module name="request-attr"/>

Uses the "request-attr" input module to obtain a value and applies the given JXPath expression to it.

<function name="java.lang.String" prefix="str"/>

Imports the class "String" as extension class to the JXPathContext using the prefix "str". Thus "str:length(xpath)" would apply the method "length" to the string object obtained from the xpath expression. Please note that the class needs to be fully qualified.

<package name="java.util" prefix="util"/>

Imports all classes in the package "java.util" as extension classes to the JXPathContext using the prefix "util". Thus "util:Date.new()" would create a new java.util.Date object.

For an example, let us assume we have a Java object called "user" in the session. We can get the username from this object via its getUsername() method. We want to be able to get at this username from the sitemap. So, in cocoon.xconf:

<input-modules>
  ...
  <component-instance 
     class="org.apache.cocoon.components.modules.input.JXPathMetaModule" 
     logger="core.modules.input" 
     name="user-attr">
    <input-module name="session-attr"/>
    <parameter>user</parameter>
  </component-instance>
  ...
</input-modules>

Then, in our sitemap, we can say:

<map:read src="home/{user-attr:username}/somefile.xml"/>

Thus the {user-attr:username} code will effectively return {session.getAttribute("user").getUsername().

LocateResource

Locate a resource in a resource tree. Any attribute name is interpreted as a URI with the last part being the resource name unless it ends with a slash. The URI is checked if the resource exists and the URI is returned. If the resource does not exist, the URI is shortened until the resource name is found and the new URI is returned. If no resource with the given name exists, null is returned.

A use case is to locate the closest menu file or when moving a site from a filesystem path == URL system from a httpd to Cocoon and provide similar functions to .htaccess files.

Example: for context:/some/path/to/a/file.xml the following URIs are tested: context:/some/path/to/a/file.xml, context:/some/path/to/file.xml, context:/some/path/file.xml, context:/some/file.xml, and context:/file.xml. For the attribute name context:/some/path/foo/ tests context:/some/path/foo/, context:/some/path/, context:/some/, and context:/ are tested.

The getAttribute() method will return the URI for the first match while getAttributeValues() will return an array of all existing paths. getAttributeNames() will return an Iterator to an empty collection.

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. Possible use is to propagate data from flow through request attributes to database actions. The same can be achieved by using the JXPathMetaModule.

Configuration: "input-module", "object", "parameter"

NamingInputModule

NamingInputModule accesses values stored in the JNDI context.

This module accept any configuration parameters and passes them as properties to the InitialContext. When connecting to the Naming context of the server Cocoon is running in, no parameters are required.

Example module configuration when connecting to external WebLogic server:

<java.naming.factory.initial>weblogic.jndi.WLInitialContextFactory</java.naming.factory.initial>
<java.naming.provider.url>t3://localhost:7001</java.naming.provider.url>

Example usage:

<map:generate src="{naming:java:comp/env/greeting}"/>

This lookups greeting entry from the environment of the webapp. Webapp's web.xml should define this entry:

   <env-entry>
     <env-entry-name>greeting</env-entry-name>
     <env-entry-value>Hello, World</env-entry-value>
     <env-entry-type>java.lang.String</env-entry-type>
   </env-entry>

NullInputModule

NullInputModule returns a null object. Use this if you want to explicitly forbid a parameter to be filled. E.g. a database column shall be filled with a default value, your forms never contain that parameter but you don't want anyone to provide this parameter manually.

PortletURLModule

Input module to be used in together with LinkRewriterTransformer in JSR-168 (Portlet) environment. Allows creation of render, action, and resource URLs using syntax:

  • portlet:action:<path> for action URL;
  • portlet:render:<path> for render URL;
  • portlet:resource:<path> for resource URL;

Outside of portlet environment, prefixes (portlet:action:, portlet:render:, portlet:resource:) are omitted.

PropertiesFileModule

Input module for accessing properties in a properties file.

The properties file can only be configured statically and is resolved via the SourceResolver system.

RandomNumberModule

RandomNumberModule returns a random number as a string. Configuration through child elements: "min", "max" setting range of random number. Defaults to "0" and "9999999999" respectively.

RawRequestParameterModule

This module allows access to "raw" request parameters and their values.

Values returned are "URL Encoded", meaning if a parameter is submitted as "foo+bar", you will get the string "foo+bar".

Note
For access to URL-Decoded request parameters, see the RequestParameterModule.

cocoon.xconf usage:

<input-modules>
  ...
  <component-instance 
     class="org.apache.cocoon.components.modules.input.RawRequestParameterModule" 
     logger="core.modules.input" 
     name="raw-request-param"/>
  ...
</input-modules>

Example Pipeline Fragment:

<map:match pattern="amazonProxy">
  <map:generate type="file" 
      src="http://localhost:8888/search?qry={raw-request-param:actor}"/>
  <map:serialize type="xml"/>
</map:match>

This input module is useful when you are querying a remote service, and you need to be able to send a search string with spaces or other special characters intact. If you were to simply use {request-param:actor}, you would end up sending a space character to the remote service, which would be an error, since RFC 1738 requires spaces and other special characters to be correctly encoded.

RealPathModule

RealPathModule provides a real filesystem path for a virtual context-relative path. If this mapping cannot be performed (e.g. Cocoon is running in a .war file), null will be returned.

RequestAttributeModule

RequestAttributeModule accesses request attributes. If the attribute name contains an asterisk "*" this is considered a wildcard and all attributes that would match this wildcard are considered to be part of an array of that name for getAttributeValues. Only one "*" is allowed.

RequestModule

RequestModule provides access to Request object properties. To get access to request properties use XPath syntax, e.g. to get the request context path use 'contextPath' as the attribute name.

More complex expressions are also supported, e.g.:

 'userPrincipal/name' 

will return the name property of the Principal object returned by the request.getUserPrincipal() method. If requested object is not found then an exception will be thrown.

RequestParameterModule

This module allows access to request parameters. Values returned are "URL Decoded". That is, if a request parameter is submitted as foo+bar, you will get the string "foo bar".

Note
For URL-Encoded request parameters, see the RawRequestParameterModule.

cocoon.xconf usage:

<input-modules>
  ...
  <component-instance 
     class="org.apache.cocoon.components.modules.input.RequestParameterModule" 
     logger="core.modules.input" 
     name="request-param"/>
  ...
</input-modules>

Example Pipeline Fragment:

<map:match pattern="bar">
   <map:generate type="file" src="documents/{request-param:file}"/>
   <map:transform src="stylesheets/{request-param:stylesheet}"/>
   <map:serialize/>
</map:match>

This pipeline will match a request for "bar" and pass the request parameters "file" and "stylesheet" to the generator and transformer, respectively. (e.g. http://localhost:8080/cocoon/bar?file=doc.xml&stylesheet=main.xsl).

Directly passing request parameters for file access can be dangerous. Remember to follow basic webapp safety rules when designing your pipelines, and when passing around request parameters.

RequestURIModule

Returns the URI of the request.

If you are familliar with Avalon and Cocoon's component architecture, the following will explain what is specifically returned:

String uri = ObjectModelHelper.getRequest(objectModel).getSitemapURI();

cocoon.xconf usage:

<input-modules>
  ...
  <component-instance 
     class="org.apache.cocoon.components.modules.input.RequestURIModule" 
     logger="core.modules.input" 
     name="request-uri"/>
  ...
</input-modules>

Example Sitemap Usage:

{request-uri:requestURI}

This is how you would use the module most of the time, since the module only returns one item, the Request URI.

Note
The same effect can be achieved by passing the parameter name "sitemapURI" to the request module. Therefore this component is not declared in cocoon.xconf by default. You must manually add it.

SelectMetaInputModule

Configuration

input-module

Configuration and name of input module used for the selection.

req

String

null

when

Selection case, condition in test attribute, input module name in name attribute. Optional configuration as nested content.

req

String

null

otherwise

Default selection case. If not present and no case matches, null is returned.

String

null

SessionAttributeModule

essionAttributeModule accesses session attributes. If the attribute name contains an asterisk "*" this is considered a wildcard and all attributes that would match this wildcard are considered to be part of an array of that name for getAttributeValues. Only one "*" is allowed.

SessionModule

SessionModule provides access to Session object properties. To get access to session properties use XPath syntax, e.g. to get the session id use 'id' as the attribute name.
More complex expressions with functions are also supported, e.g.:

 'substring(id, 8)' 

will return the substring of id property of the session object. NOTE: The module does not create a new session.

SimpleMappingMetaModule

Meta module that obtains values from an other module and by replacing the requested attribute name with another name. This is done first through a replacement table and may additionally prepend or append a string. Replacement works in both ways, it is applied to the returned attribute names as well.

Example configuration:

 <prefix>cocoon.</prefix>
 <suffix>.attr</suffix>
 <mapping in="foo" out="bar"/>
 <mapping in="yuk" out="yeeha"/>

Will map a parameter "foo" to the real one named "cocoon.bar.attr". If parameters "cocoon.yeeha.attr" and "shopping.cart" exist, the iterator will return "yeeha". "shopping.cart" does not contain the pre-/ suffix and thus is dropped.

Similarily, rm-prefix and rm-suffix will be removed from the attribute name.

SitemapVariableHolder

This "component" is a trick to get global variables on a per sitemap base.

StringConstantModule

StringConstantModule returns a constant string. Constant must be the only content of the configuration object.

SystemPropertyModule

SystemPropertyModule is an JXPath based InputModule implementation that provides access to system properties. Available system properties are defined by Java's System.getProperties(). JXPath allows to apply XPath functions to system properties. If there is a security manager, its checkPropertiesAccess method is called with no arguments. This may result in a security exception which is wrapped into a configuration exception and re-thrown.

URLDecodeModule

This module provides functionality for converting a String from the application/x-www-form-urlencoded MIME format. It is useful for example for calling remote services:

<map:generate src="http://remote/page?param1={url-decode:{request-param:param1}}"/>

Module configuration takes only one configuration parameter: "encoding" which is a target string encoding. This is utf-8 by default.

URLEncodeModule

This module provides functionality for converting a String to the application/x-www-form-urlencoded MIME format. It is useful for example for calling remote services:

<map:generate src="http://remote/page?param1={url-encode:{request-param:param1}}"/>

Module configuration takes only one configuration parameter: "encoding" which is a target string encoding. This is utf-8 by default.

XMLFileModule

This module provides an Input Module interface to any XML document, by using XPath expressions as attribute keys. The XML can be obtained from any Cocoon Source (e.g., cocoon:/..., context://.., and regular URLs). Sources can be held in memory for better performance and reloaded if changed.

Caching and reloading can be turned on / off (default: on) through <reloadable>false</reloadable> and <cacheable>false</cacheable>. The file (source) to use is specified through <file src="protocol:path/to/file.xml" reloadable="true" cacheable="true"/> optionally overriding defaults for caching and or reloading.

In addition, xpath expressions are cached for higher performance. Thus, if an expression has been evaluated for a file, the result is cached and will be reused, the expression is not evaluated a second time. This can be turned off using the cache-xpaths configuration option.

XMLMetaModule

Meta module that obtains values from other module and returns all parameters as XML.

Config:

   <!-- in cocoon.xconf -->
   <ignore>do-</ignore>
   <strip>user.</strip>
   <input-module name="request-param"/>

   <!-- e.g. in database.xml -->
   <mode type="all" name="xmlmeta"/>
      <ignore>foo.</ignore>
      <strip>f</strip>
      <use>foo</use>
      <root>my-root</root>
      <input-module name="request-param"/>
   </mode>

If present, "ignore" gives a prefix of parameters to ignore, ignore has precedence over the "use" attribute, "strip" a prefix that will be removed from the final parameter names in the produced XML, "use" is a prefix for parameters to include in the XML, and "root" is the name of the root element in the created XML.

Input:

    foo.one = ['abc']
    foo.two = ['def']
    foo1 = ['bar']
    foo2 = ['one','two','three']
    bar = ['rubber duck']

Output:

    <my-root>
     <item name="oo1">bar</item>
     <item name="oo2">
        <value>one</value>
        <value>two</value>
        <value>three</value>
     </item>
   </my-root>

Produces Objects of type DocumentWrapper