Orbeon Forms User Guide

Other Generators

1. Introduction

Generators are a special category of processors that have no XML data inputs, only outputs. They are generally used at the top of an XML pipeline to generate XML data from a Java object or other non-XML source. Orbeon Forms provides several generators as described below. See also the URL and Request generators.

2. Scope Generator

2.1. Introduction

The Scope generator can retrieve documents from the application, session and request scopes. It can work together with the Scope serializer, or retrieve documents stored by custom processors or other application modules.

The following Java object types are supported and checked in this order:

  • org.dom4j.Document - An XML document represented using the dom4j class hierarchy.
  • org.w3c.dom.Document - An XML document represented using the W3C DOM class hierarchy.
  • java.lang.String - An XML document represented as a String.
  • java.lang.Object - Any Java object. In this case, the object is serialized to XML using Castor. An optional mapping input may specify a custom Castor mapping document.

2.2. Inputs and Outputs

Type Name Purpose Mandatory
Input config Configuration Yes
Input mapping Castor XML mapping No
Output data Result XML data Yes

The config input has the following format:

<config><key>cart</key><scope>application|session|request</scope><session-scope>application|portlet</session-scope></config>
key The <key> element contains a string used to identify the document. The same key must be used to store and retrieve a document.
scope

The <scope> element specifies in what scope the document is to be retrieved from. The available scopes are:

  • application - The application scope starts when the Web application is deployed. It ends when the Web application is undeployed. The application scope provides an efficient storage for data that does not need to be persisted and that is common for all users. It is typically used to cache information (e.g. configuration data for the application read from a database).
  • session - The session scope is attached to a given user of the Web application. It is typically used to store information that does not need to be persisted and is specific to a given user. It is typically used to cache the user's profile.
  • request - The request scope starts when an HTTP request is sent to the server. It ends when the corresponding HTTP response is sent back to the client. The request scope can be used to integrate a Orbeon Forms application with legacy J2EE servlets.
session-scope

The <session-scope> element specifies in what session scope the document is to be retrieved from. This element is only allowed when the <scope> element is set to session. The available session scopes are:

  • application - access the entire application session. This is always a valid value.
  • portlet - access the local portlet session. This is only valid if the processor is run hithin a portlet.

If the element is missing, a default value is used: application when the processor runs within a servlet, and portlet when the processor runs within a portlet.

The optional mapping input contains a custom Castor mapping document. This mapping is used only if the object retrieved can only be handled as java.lang.Object and not as one of the other types.

The data output contains the document retrieved. When the Scope generator cannot find any document in scope for the given key, it returns a "null document":

<null xsi:nil="true"/>
Note

The Session generator, previously used to retrieve documents from the session scope, is now deprecated. Use the Scope generator with session scope instead.

Note

The Bean generator, previously used to retrieve JavaBeans from the request and session scopes, is now deprecated. Use the Scope generator instead.

3. Servlet Include Generator

The Servlet Include generator, using the RequestDispatcher, calls and parses the result of another servlet running in the same Java virtual machine. The servlet can generate either XML or HTML. The generator automatically detects HTML and uses HTMLTidy to clean and parse the stream as XML.

Note

This generator works only in a servlet environment. It is not supported in portlets.

3.1. Configuration

The config input describes the servlet to call, and optionally configures the HTMLTidy process. You can specify the servlet either by name or path, and optionally specify a context path. The RelaxNG schema for this input is the following:

<element name="config" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes" xmlns="http://relaxng.org/ns/structure/1.0"><interleave><choice><element name="servlet-name"><data type="string"/></element><element name="path"><data type="string"/></element></choice><optional><element name="context-uripath"><data type="string"/></element></optional><optional><element name="tidy-options"><interleave><optional><element name="show-warnings"><choice><value>true</value><value>false</value></choice></element><optional><element name="quiet"><choice><value>true</value><value>false</value></choice></element></optional></optional></interleave></element></optional></interleave></element>

3.2. Data Output

The data output contains the result in the servlet include call.

3.3. Example

This generator calls the reports servlet in the /admin context path. Since this servlet is generating HTML, it's better to have verbose error reporting from HTMLTidy.

<p:processor name="oxf:servlet-include"><p:input name="config"><config><servlet-name>reports</servlet-name><context-path>/admin</context-path><tidy-options><show-warnings>false</show-warnings><quiet>true</quiet></tidy-options></config></p:input><p:output name="data" id="#report"/></p:processor>

4. Exception Generator

The Exception generator is usually used in an error page. It serializes to XML the data contained in a Java exception retrieved from the request scope, with the following information:

  • All the exceptions, starting from the top-level exception down to the root cause.

  • For each exception, the exception class name, message, hierachy of location information, and list of stack trace elements.

The following is an XML document resulting from an exception:

<exceptions><exception><type>org.orbeon.oxf.common.ValidationException</type><message>null, line 8, column 109, description xforms:bind element: Bind element is missing nodeset attribute null, line 8, column 109: Bind element is missing nodeset attribute</message><location><system-id/><line>8</line><column>109</column><description>xforms:bind element</description><element><xforms:bind xmlns:xforms="http://www.w3.org/2002/xforms" id="xforms-element-2" ref="/instance/a" calculate=". + 1"/></element></location><location><system-id>oxf:/ops/pfc/xforms-epilogue.xpl</system-id><line>99</line><column>66</column><description>reading processor output</description><parameters><parameter><name>name</name><value>response</value></parameter><parameter><name>id</name><value>response</value></parameter><parameter><name>ref</name><value/></parameter></parameters><element><p:output xmlns:p="http://www.orbeon.com/oxf/pipeline" name="response" id="response"/></element></location><location>...</location>...<stack-trace-elements><element><class-name>org.orbeon.oxf.common.ValidationException</class-name><method-name>wrapException</method-name><file-name>ValidationException.java</file-name><line-number>119</line-number></element>...</stack-trace-elements></exception><exception>...</exception></exceptions>

A typical error pipeline should include an Exception generator followed by one or more transformation(s), and an HTML serializer.

<p:processor name="oxf:exception"><p:output name="data" id="exception"/></p:processor>

5. Bean Generator

Note

This processor is deprecated. Please refer to the Scope generator instead.

The Bean generator serializes objects in the request or session to XML. If an object is a W3C Document (org.w3c.dom.Document), the XML for this document is sent as-is. Otherwise, the object is assumed to be a JavaBean and is serialized to XML with Castor. This generator takes two inputs:

5.1. Configuration

The configuration input describes which bean to serialize, and two optional sources. The sources can be request, session or both. If both are specified, they are tried in order. In the example below, the request is searched for the guess bean. If not found, the session is tried.

<p:input name="config"><config><attribute>guess</attribute><source>request</source><source>session</source></config></p:input>

Here is the RelaxNG schema:

<element name="config" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes" xmlns="http://relaxng.org/ns/structure/1.0"><interleave><oneOrMore><element name="attribute"><data type="string"/></element></oneOrMore><interleave><optional><element name="source"><value>request</value></element></optional><optional><element name="source"><value>session</value></element></optional></interleave></interleave></element>

5.2. Mapping Input

This input specifies the Castor mapping file. See Castor Documentation for more information on the mapping file. In most instances, the default mapping is sufficient:

<p:input name="mapping"><mapping/></p:input>

5.3. Output

The output document contains a beans root node. Each serialized bean is a child of the root node. The example above generates the following document:

<beans><guess useraguess="0"><message>Hello</message></guess></beans>