# JAXP and other Java API changes

JAXP

It is now possible to set the `Configuration` used by a `TransformerFactory` or `DocumentBuilderFactory` using the `setAttribute()` method with the attribute name `FeatureKeys.CONFIGURATION`. By reading this attribute on a `TransformerFactory`, and setting it on a `DocumentBuilderFactory`, it is possible to ensure that all documents use the same Configuration without introducing any compile-time dependencies on Saxon.

A wider range of JAXP-defined options is now supported on the `DocumentBuilderFactory` interface. For example, a request to perform XInclude processing is now accepted (though it will only work if the underlying XML parser is Xerces).

It is now possible to provide a user-written URI resolver for use by the XSLT unparsed-text() function. This must be an instance of `net.sf.saxon.trans.UnparsedTextURIResolver`, and it is set as a property of the `Controller` object (Saxon's implementation of the JAXP `Transformer`). One use case for this feature is to allow access to unparsed text files to be disabled when an untrusted stylesheet is run.

xsl:message

There have been some changes to the handling of `xsl:message` output in XSLT:

- The class nominated to receive `xsl:message` output is no longer required to be an instance of `Emitter`, it can now be any instance of `net.sf.saxon.event.Receiver` (of which `Emitter` is a subclass, so existing code should still work). The sequence of calls to this Receiver has been clarified: there is a single `open()` call at the start of the transformation, and a single `close()` call at the end; and each evaluation of an `xsl:message` instruction starts with a `startDocument()` call and ends with `endDocument()`. The `startDocument()` event has a `properties` argument indicating whether `terminate="yes"` was specified, and the `locationId` on calls such as `startElement()` and `characters()` can be used to identify the location in the stylesheet where the message data originated (this is achieved by passing the supplied `locationId` in a call to `getPipelineConfiguration().getLocator().getSystemId(locationId)`, or to `getLineNumber()` on the same object).

- A new class `net.sf.saxon.event.MessageWarner` can be selected for receiving message output; this class follows the JAXP specification by passing the message output to the `warning()` method of the current `ErrorListener`, or to the `error()` method if `terminate="yes"` is specified. For backwards compatibility reasons this has not been made the default behavior.

XPath APIs

There have been some changes to the various XPath APIs, in an attempt to make them more usable, less error-prone, and more clearly differentiated, while also improving the implementation structure. The API in package `net.sf.saxon.sxpath`, which was originally introduced as a stop-gap to avoid problems for users having difficulty with JAXP 1.3 configuration, is evolving as the main supported "native" API for people who want to make the most of Saxon functionality without diving into internals. The `net.sf.saxon.xpath` API is concentrating more on JAXP conformance and use by applications that don't want to know anything about Saxon-specific classes.

- In the `sxpath` API, there were previously conflicting statements in the documentation about whether or not it was possible to bind external variables. In fact there was a mechanism, but it was error-prone and not well documented. It is now supported and hopefully clear how it is intended to work. User-defined functions are currently not supported in this interface, unless you provide your own implementation of the new interface `XPathStaticContext`. There is now an explicit `XPathDynamicContext` object for binding the context item and variables, which makes the `XPathExpression` and `XPathEvaluator` objects thread-safe. Some fo the classes comprising this interface have been moved into the sxpath package to allow methods that are intended for interal use to be protected, thus simplifying the interface and reducing the scope for error. Generally, the API now exposes implementation details rather less than it did.

Constructing source documents

A new method for constructing source documents is now available: the `buildDocument()` method on the `Configuration` object. This supersedes other methods for building documents, such as the `buildDocument()` method on `StaticQueryContext`, and the `Builder.build()` method. However, the existing methods are retained for backwards compatibility. The new method accepts as argument any `Source` object, including an `AugmentedSource` which allows a wide range of options to be specified determining how the document is parsed and built. The general principle is that the option is taken from the `AugmentedSource` object if available, otherwise it defaults to the value set in the `Configuration`.

jar: URI scheme

On the Java platform, the `jar:` URI scheme is now supported. Previously URIs using this scheme could be dereferenced, but relative URIs could not be resolved against a base URI using this scheme. This is because the `java.net.URI` class doesn't handle such resolution, which in turn is because the syntax of URIs in this scheme does not actually follow the RFC specifications for hierarchic URIs. However, they are supported by the `java.net.URL` class, which Saxon now uses to perform resolution of these relative URIs. This means, for example, that it is possible to hold stylesheet modules in a JAR file and resolve `xs:include` and `xs:import` references between files within the same JAR archive. For details of the `jar:` scheme see the javadoc for class `java.net.JARURLConnection`.

Miscellaneous

The `StaticContext` interface has changed so that `getDefaultElementNamespace()` now returns the default namespace for elements and types as a string, no longer as an internal namespace code.

By default Saxon now allocates a new `NamePool` to each `Configuration`. Previously the default was that all `Configuration`s shared the same `NamePool`. It is still possible to share a `NamePool`, but I'm not aware of any good reasons for doing so.

Next