Processors - Other Generators

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.

Scope generator

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.

Types

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.

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 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 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.

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.

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

Data output

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

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


Exception handlings

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>&lt;xforms:bind xmlns:xforms="http://www.w3.org/2002/xforms" id="xf-2" ref="/instance/a" calculate=". + 1"/&gt;</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>&lt;p:output xmlns:p="http://www.orbeon.com/oxf/pipeline"
name="response" id="response"/&gt;</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>


Exception catcher

The exception catcher has a data input and data output and behaves like the identity processor if no exception is thrown by any processor upstream, that is processors involved in generating the content fed to its data input. However, if an exception is thrown by a processor upstream, then oxf:exception-catcher catches it and produces an <exceptions> document, like the one produced by the exception generator.

Typically, you place the exception catcher after a processor that might throw an exception, and use a <p:choose> to determine whether an exception was thrown.


Comments