<?xml version="1.0" encoding="iso-8859-1"?>
<?xml-stylesheet href="../make-menu.xsl" type="text/xsl"?><html>
<head>
<this-is section="extensibility" page="output-filters" subpage=""/>
<!--
Generated at 2011-12-09T20:47:22.916Z--><title>Saxonica: XSLT and XQuery Processing: Customizing Serialization</title>
<meta name="coverage" content="Worldwide"/>
<meta name="copyright" content="Copyright Saxonica Ltd"/>
<meta name="title"
content="Saxonica: XSLT and XQuery Processing: Customizing Serialization"/>
<meta name="robots" content="noindex,nofollow"/>
<link rel="stylesheet" href="../saxondocs.css" type="text/css"/>
</head>
<body class="main">
<h1>Customizing Serialization</h1>
<p>The output of a Saxon stylesheet or query can be directed to a user-defined output filter. This filter can be
defined either as a SAX2 <code>ContentHandler</code>, or
as a subclass of the Saxon classes <code>net.sf.saxon.event.Receiver</code>.</p>
<p>One advantage of using the Saxon classes is that more information is available
from the stylesheet, for example the attributes of the <code>xsl:output</code> element; another is
that (if you are using the schema-aware version of the product) type annotations are available on
element and attribute nodes.</p>
<p>A transformation can be invoked from the Java API using the standard JAXP method
<code>transformer.transform(source, result)</code>. The second argument must implement the
JAXP class <code>javax.xml.transform.Result</code>. To send output to a SAX <code>ContentHandler</code>,
you can wrap the <code>ContentHandler</code> in a JAXP <code>SAXResult</code> object. To send output
to a Saxon <a class="bodylink" href="../javadoc/net/sf/saxon/event/Receiver.html"><code>Receiver</code></a> (which might also be an <a class="bodylink" href="../javadoc/net/sf/saxon/serialize/Emitter.html"><code>Emitter</code></a>),
you can supply the <code>Receiver</code> directly, since the
Saxon <code>Receiver</code> interface extends the JAXP <code>Result</code> interface.</p>
<p>When running XQuery, Saxon offers a similar method on the <a class="bodylink" href="../javadoc/net/sf/saxon/query/XQueryExpression.html"><code>XQueryExpression</code></a> object:
the <code>run()</code> method. This also takes an argument of type <code>Result</code>, which may be
(among other things) a <code>SAXResult</code> or a Saxon <code>Receiver</code>.</p>
<p>Some <code>ContentHandler</code> implementations require a sequence of events corresponding
to a well-formed document (that is, one whose document node has exactly one element node and no text nodes
among its children). If this is the case, you can specify the additional output property
<code>saxon:require-well-formed="yes"</code>, which will cause Saxon to report an error if the result
tree is not well-formed.</p>
<p>As specified in the JAXP interface, requests to disable or re-enable output escaping
are also notified to the content handler by means of special processing instructions. The
names of these processing instructions are defined by the constants <code>PI_DISABLE_OUTPUT_ESCAPING</code>
and <code>PI_ENABLE_OUTPUT_ESCAPING</code> defined in class <code>javax.xml.transform.Result</code>.</p>
<p>As an alternative to specifying the destination in the <code>transform()</code> or <code>run()</code> methods,
the <a class="bodylink" href="../javadoc/net/sf/saxon/event/Receiver.html"><code>Receiver</code></a> or <code>ContentHandler</code> to be used may be specified in the
<code>method</code> attribute of the <code>xsl:output</code>
element, as a fully-qualified class name; for example
<code>method="prefix:com.acme.xml.SaxonOutputFilter"</code>. The namespace prefix is ignored, but
must be present to meet XSLT conformance rules.</p>
<p>An abstract implementation of the <a class="bodylink" href="../javadoc/net/sf/saxon/event/Receiver.html"><code>Receiver</code></a> interface is available in the
<a class="bodylink" href="../javadoc/net/sf/saxon/serialize/Emitter.html"><code>Emitter</code></a>
class. This class provides additional functionality useful if you want to serialize the result to a byte or character output
stream. If the <code>Receiver</code> that you supply as an output destination is an instance of <code>Emitter</code>,
then it has access to all the serialization parameters supplied in the <code>xsl:output</code> declaration, or made
available using the Java API.</p>
<p>See the documentation of class <a class="bodylink" href="../javadoc/net/sf/saxon/event/Receiver.html"><code>net.sf.saxon.event.Receiver</code></a> for details of the methods available, or
implementations such as <a class="bodylink" href="../javadoc/net/sf/saxon/serialize/HTMLEmitter.html"><code>HTMLEmitter</code></a> and
<a class="bodylink" href="../javadoc/net/sf/saxon/serialize/XMLEmitter.html"><code>XMLEmitter</code></a> and <a class="bodylink" href="../javadoc/net/sf/saxon/serialize/TEXTEmitter.html"><code>TEXTEmitter</code></a> for
the standard output formats supported by Saxon.</p>
<p>It can sometimes be useful to set up a chain of <code>Receiver</code>s working as a pipeline. To write a filter
that participates in such a pipeline, the class <a class="bodylink" href="../javadoc/net/sf/saxon/event/ProxyReceiver.html"><code>ProxyReceiver</code></a> is supplied.
See the class <a class="bodylink" href="../javadoc/net/sf/saxon/serialize/XMLIndenter.html"><code>XMLIndenter</code></a>,
which handles XML indentation, as an example of how to write a <code>ProxyReceiver</code>.</p>
<p>Saxon sets up such a pipeline when an output file is opened, using a class called the <a class="bodylink" href="../javadoc/net/sf/saxon/lib/SerializerFactory.html"><code>SerializerFactory</code></a>.
You can override the standard <code>SerializerFactory</code> with your own subclass, which you can nominate to the <code>setSerializerFactory()</code>
method of the <a class="bodylink" href="../javadoc/net/sf/saxon/Configuration.html"><code>Configuration</code></a>. This uses individual methods to create each stage of the pipeline,
so you can either override the method that constructs the entire pipeline, or override a method that creates one
of its stages. For example, if you want to subclass the <a class="bodylink" href="../javadoc/net/sf/saxon/serialize/XMLEmitter.html"><code>XMLEmitter</code></a> (perhaps to force all non-ASCII
characters to be output as hexadecimal character references), you can override the method <code>newXMLEmitter()</code>
to return an instance of your own subclass of <code>XMLEmitter</code>, which might override the method
<code>writeEscape()</code>.</p>
<p>Rather than writing an output filter in Java, Saxon also allows you to process the output through
another XSLT stylesheet. To do this, simply name the next stylesheet in the <code>saxon:next-in-chain</code> attribute
of <code>xsl:output</code>. </p>
<p>Any number of user-defined attributes may be defined on <code>xsl:output</code>. These
attributes must have names in a non-null namespace, which must not be either the XSLT
or the Saxon namespace.
The value of the attribute is inserted into the <code>Properties</code> object made available to
the <code>Emitter</code> handling the output; they will be ignored by the standard output methods,
but can supply arbitrary information to a user-defined output method. The name of the
property will be the expanded name of the attribute in JAXP format, for example
<code>{http://my-namespace/uri}local-name</code>, and the value will be the value as given,
after evaluation as an attribute value template.</p>
<table width="100%">
<tr>
<td>
<p align="right"><a class="nav" href="collation.xml">Next</a></p>
</td>
</tr>
</table>
</body>
</html>
