The HTTP serializer performs streaming. If its input data consists of a stream of short character SAX events, such as those produced by the Request generator the URL generator, the SQL processor, or converter processors, it is possible to serialize an "infinitely" long document.
HTTP Serializer
- 1. Scope
- 2. Configuration
- 3. Content Type
- 4. Binary Mode
- 4.1. Input Document Format
- 4.2. Example
- 5. Text Mode
- 5.1. Input Document Format
- 5.2. Character Encoding
- 5.3. Specifying Headers
- 5.4. Example
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.
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.
2. Configuration
The configuration consists of the following optional elements:
| Element Name | Type | Purpose | Default Value |
|---|---|---|---|
| status-code | valid HTTP status code | HTTP status code sent to the client | SC_OK (HTTP code 100) |
| error-code | valid HTTP error code | HTTP error code sent to the client | none |
| content-type | content type, without any attributes | Indicates the content type to send to the client (see decision algorithm below). | application/octet-stream for binary mode, text/plain for text mode
|
| force-content-type | boolean |
Indicates whether the content type provided has precedence (see
decision algorithm below). This requires a
content-type element.
|
false |
| ignore-document-content-type | boolean | Indicates whether the content type provided by the input document should be ignored (see decision algorithm below). | false |
| encoding | valid encoding name | Indicates the text encoding to send to the client (see decision algorithm below). | utf-8 |
| force-encoding | boolean |
Indicates whether the encoding provided has precedence (see
decision algorithm below). This requires an
encoding element.
|
false |
| ignore-document-encoding | boolean | Indicates whether the encoding provided by the input document should be ignored (see decision algorithm below). | false |
| 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 | |
| cache-control/use-local-cache | boolean | 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 |
| empty-content | boolean | Forces the serializer to return an empty content, without reading its data input. | false |
Example:
<config><content-type>image/jpeg</content-type><header><name>Content-Disposition</name><value>attachment; filename=image.jpg</value></header></config>
3. Content Type
The content type sent to the HTTP output is determined according to the following priorities:
-
Use the content type in the
content-typeelement of the configuration ifforce-content-typeis set totrue. -
Use the content type set in the input document with the
content-typeattribute, if any, unless theignore-document-content-typeelement of the configuration is set totrue. -
Use the content type in the
content-typeelement of the configuration, if specified. -
Use
application/octet-streamin binary mode, ortext/plainin text mode.
4. Binary Mode
4.1. 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 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.
4.2. 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>
5. Text Mode
5.1. 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 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.
5.2. Character Encoding
The character encoding sent to the HTTP output is determined according to the following priorities:
-
Use the encoding in the
encodingelement of the configuration ifforce-encodingis set totrue. -
Use the encoding set in the input document with the
content-typeattribute, if any, unless theignore-document-encodingelement of the configuration is set totrue. -
Use the encoding in the
encodingelement of the configuration, if specified. -
Use
utf-8.
5.3. 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>
5.4. 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>
Note
Note
When using the command-line mode, instead of sending the output through HTTP, the HTTP serializer sends its output to the standard console 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.
Note
The HTTP serializer sends the cache control HTTP headers, including
Last-Modified, Expires and Cache-Control.
The Content-Type and Content-Length headers are also
supported.