InputModules

THE CONTENT OF THIS PAGE IS ADDED TO THE CORE DOCUMENTATION AND WILL BE DISPLAYED THERE IN THE NEXT UPDATE do not edit this page any more 2005/10/05 PA

- TARGET-AUDIENCE: *all*
- COCOON-RELEASES: 2.0.4
- DOCUMENT-STATUS: *draft* reviewed released

---

Basic information about the InputModules available in Cocoon 2.0.4. Descriptions are taken from comments in the source code of each file (see also http://cocoon.apache.org/2.1/apidocs/org/apache/cocoon/components/modules/input/package-summary.html). Provided here as a quick reference for new Cocoon users/developers. -- BenjaminYoung

Where noted, a given module extends AbstractJXPathModule, which means that you can use XPath expressions to access objects and their members/fields.

See Modules at the Cocoon Website for more information including some examples.

The preconfigured module prefixes can be found here (cocoon 2.2 trunk): cocoon-core-modules-input.xconf and cocoon-core-modules-input-flowscript.xconf for the flowscript block.

---

AbstractInputModule

This module gives you the infrastructure for easily deploying more InputModules. In order to get at the Logger, use getLogger().

---

Abstract JXPathModule

This module allows access to 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. The JXPathMetaModule is based on this class and duplicates the code since multiple inheritance is not possible. Please keep both classes in sync.

Configuration example:

<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

This module 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().

---

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:

input-module

• Name of the input module used to obtain the value and its configuration

member

• Collection member:

---

DateInputModule

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

• Java Date Format

Note: 'format' attribute doesn't seem to work. Nested <format/> tags work fine.

Example of using date in a sitemap:

        <!-- Get file based on the current date -->
         <map:match pattern="current.html">
            <map:generate src="content/{date:yyyy-mm}.xml"/>
              ...

---

GlobalInputModule

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

cocoon.xconf usage:

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

sitemap.xmap 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>

---

RandomNumberModule

Returns a random number (between 0 and 9999999999, user-configurable) as a string.

cocoon.xconf usage:

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

---

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

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

cocoon.xconf usage:

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

Example Pipeline Fragment:

<map:match pattern="fooProxy">
  <map:generate type="file" 
      src="http://xml.foo.com/onca/foo?foo={raw-request-param:foo}"/>
  <map:serialize type="xml"/>
</map:match>

This input module is useful when you are querying a remote service (in this example, a fictional 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:foo} }}, you could 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.

---

RequestModule (JXPath)

This module allows access to various useful properties of the request object (cookies, remoteAddr, remoteUser, etc).

This list may not be complete, see the Cocoon request API docs for all of the getXXX methods.

For a complete listing of all available properties, see the Cocoon Request API Docs.

cocoon.xconf usage:

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

Example Pipeline Fragment:

<map:match pattern="foo">
  <map:generate type="file" src="documents/{global:doc}"/>
  <map:transform src="stylesheets/foo2html.xsl">
    <map:parameter name="requestQueryString" value="{request:queryString}"/>
    <map:parameter name="contextPath" value="{request:contextPath}"/>
    <map:parameter name="lastVisitCookie" value="{request:cookies[name='lastVisit']/@value}"/>
  </map:transform>
  <map:serialize/>
</map:match>

---

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

For URL-Encoded request parameters, see the RawRequestParameterModule.

If you have multiple parameters with the same name, and want to get one of them, say the 2nd one, you'll have to use the RequestModule, that has JXPath features, like in this sample:

<map:parameter name='my-parameter' value='{request:getParameterValues(.,"myParameter")[2]}'/>

cocoon.xconf usage:

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

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

Note that directly passing request parameters for file access can be dangerous. Remember to follow basic webapp safety rules when designing your pipelines.

---

RequestURIModule

Returns the URI of the request. Specifically:

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

cocoon.xconf usage:

<component-instance 
  class="org.apache.cocoon.components.modules.input.RequestURIModule" 
  logger="core.modules.input" 
  name="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.

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.

---

SessionModule (JXPath)

Access various information about a session.

cocoon.xconf usage:

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

The following is not a complete list; For a complete listing of all available accessors, the Cocoon Session API Docs may be useful.

---

SessionAttributeModule

Access session attributes.

cocoon.xconf usage:

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

Example Sitemap Usage:

You could use the Session Attribute module to access a "userid" session attribute and put its value into a URI in the sitemap: <map:redirect-to uri="login?userid={session-attr:userid}" />

---

SystemPropertyModule (JXPath)

This module allows you to access system properties as returned by System.getProperties(). (See also: System.getProperties)

cocoon.xconf usage:

<component-instance 
  class="org.apache.cocoon.components.modules.input.SystemPropertyModule" 
  logger="core.modules.input" 
  name="system-property"/>

---

XMLFileModule (JXPath)

This module provides an interface into any XML document (Using XPath expressions), and is therefore very powerful.

XML can be obtained using any Cocoon Source (e.g. cocoon:/, context:/, http://, etc). 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.

cocoon.xconf usage:

<component-instance 
  class="org.apache.cocoon.components.modules.input.XMLFileModule" 
  logger="core.modules.xml" 
  name="myxml">

  <file src="context:///samples/modules/forrestconf.xml"/>
</component-instance>

---

RealPath Module

Returns the real path of a context-relative virtual path (if not deployed from a .war). e.g.

The real path is relative to the webapp-context, not to the sitemap. Sometimes, you would rather have a path relative to the sitemap. This is taken care of in the non-standard SitemapPathModule.