Other Serializers
1. Scope
Serializers are processors with no XML output. A serializer, just like any
processor, can access files, connect to databases, and take actions depending on its
inputs. See also the HTTP serializer.
2. URL Serializer
The URL Serializer mirrors the functionality of the URL Generator. Instead of reading
from of URL, it writes its data input as XML in a URL. Note that only
the oxf: and http: protocols allows writing at this time.
Note
The
Flat File Resource
Manager is the only Resource Manager supporting write operations.
The URL serializer takes a config input with a single url
element containing the URL to write to. The data input is serialized
according the rules of the XML Serializer.
<p:processor name="oxf:url-serializer" xmlns:p="
http://www.orbeon.com/oxf/pipeline"
> <p:input name="config"> <config> <url>oxf:/path/current.xml</url>
</config> </p:input> <p:input name="data" href="#xml-data"/>
</p:processor>
3. File Serializer
The File Serializer is most useful in a command-line application. When executed, this
serializer writes its data input into the file specified in the config
element. Here is an example:
<p:processor name="oxf:file-serializer" xmlns:p="
http://www.orbeon.com/oxf/pipeline"
> <p:input name="config"> <config> <file>test.html</file>
<directory>c:/build/doc</directory>
<content-type>text/html</content-type>
<public-doctype>-//W3C//DTD HTML 4.01//EN</public-doctype>
<system-doctype>http://www.w3.org/TR/html4/strict.dtd</system-doctype>
<encoding>utf-8</encoding>
<indent-amount>4</indent-amount>
</config> </p:input> <p:input name="data" href="#html"/>
</p:processor>
The file element specifies the file to write to.
The directory element is optional. If specified, it is used as a base
directory for the file element.
The content-type element is optional. The default is
application/xml. Other valid values are text/html and
text/plain.
The following optional attributes can also be specified:
public-doctype, system-doctype, encoding,
indent and indent-amount.
4. Scope Serializer
The Scope serializer can store documents into the application, session and request
scopes. It works together with the Scope generator.
The Scope serializer has a config input in 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 stored. 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.
|
In addition to the config input, the Scope serializer has a
data input receiving the document to store.
Note
The Session serializer, previously used, is now deprecated. Use the Scope
serializer with session scope instead.
5. Null Serializer
The Null Serializer acts as a black hole. The data input is read and
ignored. This processor is useful when a pipeline or a branch of a
p:choose element doesn't have to return any document.
<p:processor name="oxf:null-serializer" xmlns:p="
http://www.orbeon.com/oxf/pipeline"
> <p:input name="data" href="#document"/>
</p:processor>
6. Flushing the Output Stream
All serializers (XML, HTML, text, and FOP) will flush their output stream when they
encounter the following processing instruction: <?oxf-serializer
flush?>
This instruction allows the browser to display a Web page
incrementally. Incremental display is typically useful when sending large tables or
when the first part of a Web page could be displayed, while the rest of the page
cannot until a time consuming action is performed.
7. Legacy HTTP Serializers
These serializers share a common functionality: writing their data input to an HTTP
response. Typically, this means sending data back to a client web browser. This can
be done in a Servlet environment or a Portlet environment. All share the same
configuration, but differ in how they convert their input data. The following
describes the common configuration, then the specifics for each serializer.
Note
When using the command-line mode, instead of sending the output through HTTP, the
HTTP serializers send their output to the standard output. In such a case, the
parameters that do not affect the content of the data, such as content-type,
status-code, etc. are ignored.
All serializers send the cache control HTTP headers, including
Last-Modified, Expires and Cache-Control.
The content type and content length headers are also supported.
7.1 Configuration
The configuration consists of the following optional elements.
Element |
Purpose |
Default |
content-type |
content type sent to the client |
Specific to each serializer |
encoding |
The default text encoding |
utf-8 |
status-code |
HTTP status code sent to the client |
SC_OK, or 100 |
error-code |
HTTP error code sent to the client |
none |
empty-content |
Forces the serializer to return an empty content, without reading its data input |
false |
version |
HTML or XML version number |
4.01 for HTML (ignored for XML, which always output 1.0) |
public-doctype |
The public doctype |
"-//W3C//DTD HTML 4.01 Transitional//EN" for HTML, none otherwise |
system-doctype |
The system doctype |
"http://www.w3.org/TR/html4/loose.dtd" for HTML, none otherwise |
omit-xml-declaration |
Specifies whether an XML declaration must be omitted |
false for XML and HTML (i.e. a declaration is output by default), ignored otherwise |
standalone |
If true, specifies standalone="yes" in the document
declaration. If false, specifies standalone="no" in the
document declaration.
|
not specified for XML, ignored otherwise |
indent |
Specifies if the output is indented |
true |
indent-amount |
Specifies the number of indentation space |
1 |
cache-control/use-local-cache |
Whether the resulting stream must be locally cached. For documents
or binaries that are large or known to change at every request, it
is recommended to set this to false.
|
true |
header |
Adds a custom HTTP header to the response. The nested elements
name and value contain the name and value
of the header, respectively. You can add multiple headers.
|
none |
<config> <content-type>text/html</content-type>
<status-code>100</status-code>
<empty-content>false</empty-content>
<error-code>0</error-code>
<version>4.01</version>
<public-doctype>-//W3C//DTD HTML 4.01//EN</public-doctype>
<system-doctype>http://www.w3.org/TR/html4/strict.dtd</system-doctype>
<omit-xml-declaration>false</omit-xml-declaration>
<standalone>true</standalone>
<encoding>utf-8</encoding>
<indent-amount>4</indent-amount>
<cache-control> <use-local-cache>true</use-local-cache>
</cache-control> <header> <name>Content-Disposition</name>
<value>attachment; filename=image.jpeg;</value>
</header> </config>
7.2 XML Serializer
This serializer writes XML text. The output is indented with no spaces and
encoded using the UTF-8 character set. The default content type is
application/xml.
<p:processor name="oxf:xml-serializer" xmlns:p="
http://www.orbeon.com/oxf/pipeline"
> <p:input name="config"> <config> <content-type>text/vnd.wap.wml</content-type>
</config> </p:input> <p:input name="data" href="#wml"/>
</p:processor>
7.3 HTML Serializer
The HTML Serializer's output conforms to the XSLT html semantic.
The doctype is set to HTML
4.0 Transitional and the content is indented with no space and encoded
using the UTF-8 character set. The default content type is
text/html. The following is a simple HTMLSerializer example:
<p:processor name="oxf:html-serializer" xmlns:p="
http://www.orbeon.com/oxf/pipeline"
> <p:input name="config"> </p:input> <p:input name="data" href="#html"/>
</p:processor>
7.4 Text Serializer
The Text Serializer's output conforms to the XSLT text semantic.
The output is encoded using the UTF-8 character set. This serializer is
typically useful for pipelines generating Comma Separated Value (CSV) files.
The default content type is text/plain.
<p:processor name="oxf:text-serializer" xmlns:p="
http://www.orbeon.com/oxf/pipeline"
> <p:input name="config"> </p:input> <p:input name="data" href="#text"/>
</p:processor>