<?xml version="1.0" encoding="iso-8859-1"?>
<?xml-stylesheet href="../../make-menu.xsl" type="text/xsl"?><html>
<head>
<this-is section="changes" page="intro93" subpage="s9api-93"/>
<!--
Generated at 2011-12-09T20:47:22.916Z--><title>Saxonica: XSLT and XQuery Processing: Changes to the s9api API</title>
<meta name="coverage" content="Worldwide"/>
<meta name="copyright" content="Copyright Saxonica Ltd"/>
<meta name="title"
content="Saxonica: XSLT and XQuery Processing: Changes to the s9api API"/>
<meta name="robots" content="noindex,nofollow"/>
<link rel="stylesheet" href="../../saxondocs.css" type="text/css"/>
</head>
<body class="main">
<h1>Changes to the s9api API</h1>
<p>The <a class="bodylink" href="../../javadoc/net/sf/saxon/s9api/XsltTransformer.html"><code>XsltTransformer</code></a> interface has two new methods, <code>setURIResolver()</code> and <code>getURIResolver()</code>.
These define the <code>URIResolver</code> used for resolving calls to <code>doc()</code> and <code>document()</code>.</p>
<p>The <a class="bodylink" href="../../javadoc/net/sf/saxon/s9api/DocumentBuilder.html"><code>DocumentBuilder</code></a> class has a new method <code>newBuildingStreamWriter()</code>.
This gives access to a class that allows a Saxon document tree
to be built programmatically by writing Stax <code>XMLStreamWriter</code> events. This is a lot easier than the previous alternatives, of generating SAX events
or Saxon <a class="bodylink" href="../../javadoc/net/sf/saxon/event/Receiver.html"><code>Receiver</code></a> events. This mechanism is supported by an underlying class
<a class="bodylink"
href="../../javadoc/net/sf/saxon/event/StreamWriterToReceiver.html"><code>StreamWriterToReciever</code></a>
which converts Stax <code>XMLStreamWriter</code> events
into Saxon <code>Receiver</code> events. <i>Note:</i> this class does not cache the <code>NamePool</code>: it may therefore generate a high level of contention if used in a multithreading
environment.</p>
<p>Similarly, the <a class="bodylink" href="../../javadoc/net/sf/saxon/s9api/DocumentBuilder.html"><code>DocumentBuilder</code></a> class has a new method <code>newContentHandler()</code>.
This returns a SAX <code>ContentHandler</code> to
which events may be sent to build a tree programmatically. Although slightly less convenient than the <code>XMLStreamWriter</code> interface, this
is useful for the many cases where an existing application already generates SAX events.</p>
<p>The specification of the <a class="bodylink" href="../../javadoc/net/sf/saxon/s9api/XdmDestination.html"><code>XdmDestination</code></a>
class has been clarified to state that the event stream written
to the <code>XdmDestination</code> must constitute either a single tree that is rooted at a document or element node,
or an empty sequence; and the implementation has been changed to enforce this. This means
that when this class is used for the destination of an XQuery query, an exception is thrown if the query returns
atomic values, nodes other than document or element nodes, or sequences of multiple nodes. Previously
the effect in such cases was poorly specified and could lead to internal exceptions with poor diagnostics.</p>
<p>The <a class="bodylink" href="../../javadoc/net/sf/saxon/s9api/XdmNode.html"><code>XdmNode</code></a> class now has a public constructor allowing a
<a class="bodylink" href="../../javadoc/net/sf/saxon/om/NodeInfo.html"><code>NodeInfo</code></a> to be wrapped.</p>
<p>The <a class="bodylink" href="../../javadoc/net/sf/saxon/s9api/Processor.html"><code>Processor</code></a> class now has a public constructor allowing a
<a class="bodylink" href="../../javadoc/net/sf/saxon/Configuration.html"><code>Configuration</code></a> to be wrapped.</p>
<p>The <a class="bodylink" href="../../javadoc/net/sf/saxon/s9api/Processor.html"><code>Processor</code></a> class now has a number of convenience
factory methods allowing a <a class="bodylink" href="../../javadoc/net/sf/saxon/s9api/Serializer.html"><code>Serializer</code></a> to be constructed.
There is also a method <code>setProcessor()</code> that allows the <code>Serializer</code> to retain a connection with a <code>Processor</code>, and hence a
configuration. This enables new methods on the <code>Serializer</code> to be simplified, avoiding the need to supply a <code>Processor</code>
(or Configuration) on the method call. Eventually the free-standing constructors on <code>Serializer</code> may be deprecated.</p>
<p>The <a class="bodylink" href="../../javadoc/net/sf/saxon/s9api/Serializer.html"><code>Serializer</code></a> class has two new convenience methods,
allowing serialization of an <a class="bodylink" href="../../javadoc/net/sf/saxon/s9api/XdmNode.html"><code>XdmNode</code></a> to an arbitrary <a class="bodylink" href="../../javadoc/net/sf/saxon/s9api/Destination.html"><code>Destination</code></a>,
or more simply to a Java string.</p>
<p>The <a class="bodylink" href="../../javadoc/net/sf/saxon/s9api/Serializer.html"><code>Serializer</code></a> class has a new method <code>getXMLStreamWriter()</code>,
allowing an <code>XMLStreamWriter</code>
to be constructed as a front-end to this <code>Serializer</code>. This is a very convenient way of generating serialized XML output from a Java
application: for an example of its use, see the XSLT test suite driver in the samples directory.</p>
<p>The <a class="bodylink" href="../../javadoc/net/sf/saxon/s9api/XPathCompiler.html"><code>XPathCompiler</code></a> object now has the ability to maintain a cache of
compiled XPath expressions. If this feature is enabled, any attempt to compile
an expression first causes a lookup in the cache to see whether the same expression has already been compiled. The cache is cleared
if any changes to the static context are made (for example, changing the namespace declarations in force).</p>
<p>The <a class="bodylink" href="../../javadoc/net/sf/saxon/s9api/XPathCompiler.html"><code>XPathCompiler</code></a> object has two new convenience methods, <code>evaluate()</code> and <code>evaluateSingle()</code>, allowing
an expression to be compiled and executed with a single call. This works especially well when the compiler is also caching compiled expressions.</p>
<p>Running a pipeline of XSLT transformations by using each <a class="bodylink" href="../../javadoc/net/sf/saxon/s9api/XsltTransformer.html"><code>XsltTransformer</code></a>
as the <a class="bodylink" href="../../javadoc/net/sf/saxon/s9api/Destination.html"><code>Destination</code></a> of the previous one is now more efficient;
the code has been changed so that the second transformation does not start until the stack and heap for the first one have been released.
This has entailed a minor change to the <code>Destination</code> interface: it now has a <code>close()</code> method; and it also means
that the <code>XsltTransformer</code> is not serially reusable. You should create a new <code>XsltTransformer</code> for each transformation
(while reusing the <a class="bodylink" href="../../javadoc/net/sf/saxon/s9api/XsltExecutable.html"><code>XsltExecutable</code></a>, of course).</p>
<p>The <a class="bodylink" href="../../javadoc/net/sf/saxon/s9api/XQueryEvaluator.html"><code>XQueryEvaluator</code></a> has a new method <code>callFunction()</code>
that allows any user-declared function within the
compiled query to be called directly from the Java application. This in effect enables the creation of a query library containing
multiple functions that can be invoked from the calling application. Note that to compile a query, it must still have a "main query"
to satisfy the syntax rules of the XQuery language.</p>
<table width="100%">
<tr>
<td>
<p align="right"><a class="nav" href="dot-net-93.xml">Next</a></p>
</td>
</tr>
</table>
</body>
</html>
