# 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.

Next