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

Note
Use of these serializers should be replaced by converters connected to the HTTP serializer.

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">
  <config/>
  </p:input>
  <p:input name="data" href="#html"/>
  </p:processor>

Note
The XML 1.0 Specification prohibits a DOCTYPE definition with a Public ID and no System ID.

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">
  <config/>
  </p:input>
  <p:input name="data" href="#text"/>
  </p:processor>