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.

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 into a URL.

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">
    <p:input name="config">
        <config>
            <url>oxf:/path/current.xml</url>
        </config>
    </p:input>
    <p:input name="data" href="#xml-data"/>
</p:processor>

File serializer

The File serializer supports decoding binary or text data encapsulated in XML documents and writing it to a file on disk. The file serializer can write to a file you choose or to a temporary file. When writting to a temporary file, you need to read the data output to get the URL of the temporary file that was produced and which will consist of an element url containing URL of the temporary file, such as: <url>file:/tmp/gaga.tmp</url>.

The configuration consists of the following elements:

Here is how you serialize a document produced by a pipeline to a file on disk:

<!-- Convert a document to serialized XML -->

<p:processor name="oxf:xml-converter">
    <p:input name="config">
        <config>
            <encoding>utf-8</encoding>
        </config>
    </p:input>
    <p:input name="data" href="#my-document"/>
    <p:output name="data" id="converted"/>
</p:processor>

<!-- Write the document to a file -->

<p:processor name="oxf:file-serializer">
    <p:input name="config">
        <config>
            <directory>build/doc/reference</directory>
            <file>single-file-doc.html</file>
            <make-directories>true</make-directories>
            <append>false</append>
        </config>
    </p:input>
    <p:input name="data" href="#converted"/>
</p:processor>

Note the use of the XML converter processor, which serializes the XML document produced by the pipeline to a textual representation of XML.

Here is how you can copy a file specified with a URL from one location to the other, by using the URL generator and the File serializer:

<!-- Read original file -->

<p:processor name="oxf:url-generator">
    <p:input name="config">
        <config>
            <url>file:/my-image.jpg</url>
        </config>
    </p:input>
    <p:output name="data" id="image-data"/>
</p:processor>

<!-- Write to another file -->

<p:processor name="oxf:file-serializer">
    <p:input name="config">
        <config>
            <file>/my-copied-image.jpg</file>
        </config>
    </p:input>
    <p:input name="data" href="#image-data"/>
</p:processor>

In the following example, data is written to a temporary file which will be deleted when the session of the current user expires. The URL of the temporary file is returned by the File serializer through its data output.

<p:processor name="oxf:file-serializer">
    <p:input name="config">
        <config>
            <scope>session</scope>
        </config>
    </p:input>
    <p:input name="data" href="#data-to-write"/>
    <p:output name="data" id="url-written"/>
</p:processor>

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>
    <session-scope>application|portlet</session-scope>
</config>

In addition to the config input, the Scope serializer has a data input receiving the document to store.

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

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.

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.

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.

Configuration

The configuration consists of the following optional elements.

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

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">
    <p:input name="config">
        <config>
            <content-type>text/vnd.wap.wml</content-type>
        </config>
    </p:input>
    <p:input name="data" href="#wml"/>
</p:processor>

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 HTML serializer example:

<p:processor name="oxf:html-serializer">
    <p:input name="config">
        <config/>
    </p:input>
    <p:input name="data" href="#html"/>
</p:processor>

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