Changes to the s9api API

The XsltTransformer interface has two new methods, setURIResolver() and getURIResolver(). These define the URIResolver used for resolving calls to doc() and document().

The DocumentBuilder class has a new method newBuildingStreamWriter(). This gives access to a class that allows a Saxon document tree to be built programmatically by writing Stax XMLStreamWriter events. This is a lot easier than the previous alternatives, of generating SAX events or Saxon Receiver events. This mechanism is supported by an underlying class StreamWriterToReciever which converts Stax XMLStreamWriter events into Saxon Receiver events. Note: this class does not cache the NamePool: it may therefore generate a high level of contention if used in a multithreading environment.

Similarly, the DocumentBuilder class has a new method newContentHandler(). This returns a SAX ContentHandler to which events may be sent to build a tree programmatically. Although slightly less convenient than the XMLStreamWriter interface, this is useful for the many cases where an existing application already generates SAX events.

The specification of the XdmDestination class has been clarified to state that the event stream written to the XdmDestination 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.

The XdmNode class now has a public constructor allowing a NodeInfo to be wrapped.

The Processor class now has a public constructor allowing a Configuration to be wrapped.

The Processor class now has a number of convenience factory methods allowing a Serializer to be constructed. There is also a method setProcessor() that allows the Serializer to retain a connection with a Processor, and hence a configuration. This enables new methods on the Serializer to be simplified, avoiding the need to supply a Processor (or Configuration) on the method call. Eventually the free-standing constructors on Serializer may be deprecated.

The Serializer class has two new convenience methods, allowing serialization of an XdmNode to an arbitrary Destination, or more simply to a Java string.

The Serializer class has a new method getXMLStreamWriter(), allowing an XMLStreamWriter to be constructed as a front-end to this Serializer. 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.

The XPathCompiler 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).

The XPathCompiler object has two new convenience methods, evaluate() and evaluateSingle(), allowing an expression to be compiled and executed with a single call. This works especially well when the compiler is also caching compiled expressions.

Running a pipeline of XSLT transformations by using each XsltTransformer as the Destination 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 Destination interface: it now has a close() method; and it also means that the XsltTransformer is not serially reusable. You should create a new XsltTransformer for each transformation (while reusing the XsltExecutable, of course).

The XQueryEvaluator has a new method callFunction() 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.