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