The Session generator, previously used to retrieve documents from the session scope, is now deprecated. Use the Scope generator with session scope instead.
Other Generators
- 1. Introduction
- 2. Scope Generator
- 2.1. Introduction
- 2.2. Inputs and Outputs
- 3. Servlet Include Generator
- 3.1. Configuration
- 3.2. Data Output
- 3.3. Example
- 4. Exception Generator
- 5. Bean Generator
- 5.1. Configuration
- 5.2. Mapping Input
- 5.3. Output
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:
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
|
session-scope |
The
If the element is missing, a default value is used:
|
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":
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.
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:
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.
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:
A typical error pipeline should include an Exception generator followed by one or more transformation(s), and an HTML serializer.
5. Bean Generator
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.
Here is the RelaxNG schema:
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:
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: