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. PresentationServer 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>
</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 PresentationServer application with legacy J2EE servlets.
|
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":
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"> <interleave> <choice> <element name="servlet-name"> </element> <element name="path"> </element> </choice> <optional> <element name="context-uripath"> </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" xmlns:p="
http://www.orbeon.com/oxf/pipeline"
> <p:input name="config"> <config> <servlet-name>reports</servlet-name>
<context-path>/admin</context-path>
<tidy-options> <show-warnings>true</show-warnings>
<quiet>false</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 pipeline. It serializes an exception
into XML. The following shows an XML stream resulting from an exception.
<exceptions> <exception> <type>class org.orbeon.oxf.common.OXFException</type>
<message>Cannot read from file /doc/pages/test</message>
<stack-trace>stack trace</stack-trace>
</exception> <exception>more exceptions</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" xmlns:p="
http://www.orbeon.com/oxf/pipeline"
> <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" xmlns:p="
http://www.orbeon.com/oxf/pipeline"
> <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"> <interleave> <oneOrMore> <element name="attribute"> </element> </oneOrMore> <interleave> <optional> <element name="source"> </element> </optional> <optional> <element name="source"> </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" xmlns:p="
http://www.orbeon.com/oxf/pipeline"
> </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"> </guess> </beans>