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.

The HTTP serializer supports decoding binary or text data encapsulated in XML documents and sending it into 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.

Configuration

The configuration consists of the following optional elements:

Example:

<config>
    <content-type>image/jpeg</content-type>
    <header>
        <name>Content-Disposition</name>
        <value>attachment; filename=image.jpg</value>
    </header>
</config>

Content type

The content type sent to the HTTP output is determined according to the following priorities:

1. Use the content type in the content-type element of the configuration if force-content-type is set to true.
2. Use the content type set in the input document with the content-type attribute, if any, unless the ignore-document-content-type element of the configuration is set to true.
3. Use the content type in the content-type element of the configuration, if specified.
4. Use application/octet-stream in binary mode, or text/plain in text mode.

Binary mode

Input document format

The binary mode is enabled when the root element of the input document contains an xsi:type attribute containing a reference to the xs:base64Encoding type.

In this mode, all the character content under the root element is considered as Base64-encoded binary content according to the binary document format, for example:

<document xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:base64Binary" content-type="image/jpeg">
/9j/4AAQSkZJRgABAQEBygHKAAD/2wBDAAQDAwQDAwQEBAQFBQQFBwsHBwYGBw4KCggLEA4R
...
KKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooA//2Q==
</document>

An optional content-type attribute provides information about the content type of the document. This attribute may be used to set the HTTP content-type header, as discussed above.

An optional last-modified attribute provides information about the last modification date of the resource, and is used by the HTTP serializer if present. In this case, the value overrides the value normally automatically computed by the HTTP serializer.

Example

Here is an example connecting the URL generator to the serializer, and the appropriate configurations:

<p:processor name="oxf:url-generator">
    <p:input name="config">
        <config>
            <!-- URL of the image file -->
            <url>oxf:/my-image.jpg</url>
            <!-- Set content type -->
            <content-type>image/jpeg</content-type>
            <!-- This makes sure that the content type specified is used and that the file is read in binary mode, even if the connection sets another content type. With the oxf: protocol, this is not strictly necessary, but if the http: protocol was used, this could be used to override the content type set by the HTTP connection. -->
            <force-content-type>true</force-content-type>
        </config>
    </p:input>
    <p:output name="data" id="image-data"/>
</p:processor>

<p:processor name="oxf:http-serializer">
    <p:input name="config">
        <config>
            <!-- This makes sure that the correct content type is sent to the client. In this particular case, this is not strictly necessary, as the content type provided by the input document would be used anyway. -->
            <content-type>image/jpeg</content-type>
            <force-content-type>true</force-content-type>
        </config>
    </p:input>
    <p:input name="data" href="#image-data"/>
</p:processor>

Text mode

Input document format

The text mode is enabled when the root element of the input document contains an xsi:type attribute containing a reference to the xs:string type.

In this mode, all the character content under the root element is considered as text content according to the text document format, for example:

<document xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string" content-type="text/plain">
Rien n'est beau comme ces maisons du siècle dix-septième dont la place Royale offre une si
majestueuse réunion. Quand leurs faces de briques, entremêlées et encadrées de cordons et de
coins de pierre, et quand leurs fenêtres hautes sont enflammées des rayons splendides du
couchant, vous vous sentez, à les voir, la même vénération que devant une Cour des parlements
assemblée en robes rouges à revers d'hermine ; et, si ce n'était un puéril rapprochement, on
pourrait dire que la longue table verte où ces redoutables magistrats sont rangés en carré
figure un peu ce bandeau de tilleuls qui borde les quatre faces de la place Royale et en
complète la grave harmonie.
</document>

An optional content-type attribute provides information about the content type of the document. This attribute may be used to set the HTTP content-type header, as discussed above. In text mode, the content-type attribute can also have a charset parameter providing a hint at the preferred character encoding for the text, as discussed below, for example text/plain; charset=iso-8859-1. Note that the XML input document infoset internally represents characters in Unicode and therefore does not require encoding information.

Character encoding

The character encoding sent to the HTTP output is determined according to the following priorities:

1. Use the encoding in the encoding element of the configuration if force-encoding is set to true.
2. Use the encoding set in the input document with the content-type attribute, if any, unless the ignore-document-encoding element of the configuration is set to true.
3. Use the encoding in the encoding element of the configuration, if specified.
4. Use utf-8.

Specifying headers

RFC 2183 describes the Content-Disposition HTTP header, used by web browsers to decide how to display an attachement. A value of inline means that a browser will try to use a plugin to display for example a PDF file. A value of attachement causes the browser to ask the user to save the file, optionally proposing a file name. The following two example show how it is possible to specify such headers with the HTTP serializer:

Using a plugin:

<p:processor name="oxf:xslfo-serializer">
    <p:input name="config">
        <config>
            <header>
                <name>Content-Disposition</name>
                <value>inline</value>
            </header>
        </config>
    </p:input>
    <p:input name="data" href="#pdf-document"/>
</p:processor>

Saving a file to disk:

<p:processor name="oxf:xslfo-serializer">
    <p:input name="config">
        <config>
            <header>
                <name>Content-Disposition</name>
                <value>attachement; filename=report.pdf</value>
            </header>
        </config>
    </p:input>
    <p:input name="data" href="#pdf-document"/>
</p:processor>

Example

Here is an example connecting the URL generator to the serializer, and the appropriate configurations:

<p:processor name="oxf:url-generator">
    <p:input name="config">
        <config>
            <!-- URL of the text file -->
            <url>oxf:/text.txt</url>
            <!-- The file will be read as plain text -->
            <content-type>text/plain</content-type>
            <!-- The file is encoded with this encoding -->
            <encoding>iso-8859-1</encoding>
        </config>
    </p:input>
    <p:output name="data" id="text-data"/>
</p:processor>

<p:processor name="oxf:http-serializer">
    <p:input name="config">
        <config>
            <!-- Make sure the client receives the text/plain content type -->
            <content-type>text-plain</content-type>
            <force-content-type>true</force-content-type>
            <!-- We specify another encoding, and force it -->
            <encoding>utf-8</encoding>
            <force-encoding>true</force-encoding>
        </config>
    </p:input>
    <p:input name="data" href="#text-data"/>
</p:processor>