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 AbstractJX!PathModule, 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 JX!PathMetaModule 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"/>

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


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

member

Attribute

Description

name

Parameter name, "*" may distinguish multiple collections

type

JDBC type name of members


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.

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

Accessor

Description

(anything)

The random number


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.

Accessor

Description

attributeNames

Returns an Enumeration containing the names of the attributes available to this request.

authType

Returns the name of the authentication scheme used to protect the servlet, for example, "BASIC" or "SSL," or null if the servlet was not protected

characterEncoding

Returns the name of the character encoding used in the body of this request.

contentLength

Returns the length, in bytes, of the request body

contentType

Returns the MIME type of the body of the request

contextPath

Returns the portion of the request URI that indicates the context of the request.

cookieMap

Returns a map of the Cookie objects the client sent with this request, indexed by name.

cookies

Returns an array containing all of the Cookie objects the client sent with this request.

headerNames

Returns an enumeration of all the header names this request contains.

headers

Returns all the values of the specified request header as an Enumeration of String objects.

locale

Returns the preferred Locale that the client will accept content in, based on the Accept-Language header.

locales

Returns an Enumeration of Locale objects indicating, in decreasing order starting with the preferred locale, the locales that are acceptable to the client based on the Accept-Language header.

method

Returns the name of the HTTP method with which this request was made, for example, GET, POST, or PUT.

parameterNames

Returns an Enumeration of String objects containing the names of the parameters contained in this request.

pathInfo

Returns any extra path information associated with the URL the client sent when it made this request.

pathTranslated

Returns any extra path information after the servlet name but before the query string, and translates it to a real path.

protocol

Returns the name and version of the protocol the request uses in the form protocol/majorVersion.minorVersion, for example, HTTP/1.1.

queryString

Returns the query string that is contained in the request URL after the path.

remoteAddr

Returns the Internet Protocol (IP) address of the client that sent the request.

remoteHost

Returns the fully qualified name of the client that sent the request, or the IP address of the client if the name cannot be determined.

remoteUser

Returns the login of the user making this request, if the user has been authenticated, or null if the user has not been authenticated.

requestedSessionId

Returns the session ID specified by the client.

requestedSessionIdFromCookie

requestedSessionIdFromURL

requestedSessionIdValid

requestURI

Returns the part of this request's URL from the protocol name up to the query string in the first line of the HTTP request.

scheme

Returns the name of the scheme used to make this request, for example, http, https, or ftp.

secure

Returns a boolean indicating whether this request was made using a secure channel, such as HTTPS.

serverName

Returns the host name of the server that received the request

serverPort

Returns the port number on which this request was received.

servletPath

Returns the part of this request's URL that calls the servlet.

session

Returns the current session associated with this request, or if the request does not have a session, creates one.

sitemapURI

Returns the URI of the requested resource as interpreted by the sitemap.

userPrincipal

Returns the login of the user making this request, if the user has been authenticated, or null if the user has not been authenticated.

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.

Accessor

Description

attributeNames

Returns a collection of attribute names in the session

creationTime

A Unix timestamp (seconds since the epoch) representing when the session was created.

id

The unique session identifier

lastAccessedTime

A Unix timestamp representing when the session was last accessed.

maxInactiveInterval

# of seconds before an inactive session is invalidated.

new

Set to "true" if the session is new, otherwise "false"


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.

Accessor

Value

/

/home/resin/webapps/cocoon/

/images

/home/resin/webapps/cocoon/images

/WEB-INF

/home/resin/webapps/cocoon/WEB-INF

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.

InputModules (last edited 2009-09-20 23:40:23 by localhost)