System Programming Interfaces

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.

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.

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.

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 Configurations shared the same NamePool. It is still possible to share a NamePool, but I'm not aware of any good reasons for doing so.