S9API interface

Support for new Java date/time system

XdmAtomicValue provides additional constructors and getter methods supporting conversion to or from: java.time.Instant, java.time.LocalDateTime, java.time.OffsetDateTime, java.time.ZonedDateTime, and java.time.LocalDate.

Tree Construction APIs

Two new APIs have been introduced to make construction of XDM trees easier. One is oriented to construction of in-memory documents, the other is an event-based push API:

• The Sapling API provides a set of very simple classes and methods to construct "sapling trees"; once constructed, these can then be converted using a single method call to a full XDM tree. They can also be used without conversion as input to a transformation, serializer, or schema validator. Sapling trees use immutable (or "persistent") data structures, so a tree can be built incrementally without the overhead of copying objects when a subtree is added to a parent tree. Details of the API can be found in the Javadoc for class SaplingNode.

• The Push API is modelled on existing APIs such as the SAX ContentHandler and the StAX XMLStreamWriter, but attempts to achieve much higher levels of usability, especially for constructing simple documents. The need for a stable API at this level arises partly because a number of Saxon users have taken to using the Receiver interface, which is complex and error-prone to use, and is not always stable between releases. The new Push API is documented at net.sf.saxon.s9api.Push. A Push provider allowing the application to write to any Destination may be obtained by calling Processor.newPush().

Serialization

The s9api Serializer object has new methods allowing any JAXP Source to be serialized. This allows for direct pass-through from an XML parser to a serializer (for example, to add indenting), for serialization of DOM trees, Sapling trees, and trees in third-party tree models.

XSLT and default namespaces

The XsltCompiler object has two new properties that can be set:

• setDefaultElementNamespace() sets the default namespace for elements and types: in effect, a default for the xpath-default-namespace attribute. (If an explicit xpath-default-namespace is present in the stylesheet, the API setting is ignored.)
• setUnprefixedElementMatchingPolicy() sets the policy for handling unprefixed element names appearing in XPath expressions and match patterns. Three values are supported: DEFAULT_NAMESPACE (this is the default, as specified in the W3C specification); ANY_NAMESPACE, which causes such names to match by local part only, ignoring the namespace; and DEFAULT_NAMESPACE_OR_NONE, which causes such names to match (a) elements in the default namespace, and (b) elements in no namespace. This is designed primarily to approximate the special rules defined in the HTML5 specification for matching unprefixed element names.

ErrorListener and ErrorReporter

A new mechanism for reporting errors to user applications has been introduced. The new ErrorReporter interface is a functional replacement for the old ErrorListener, though the ErrorListener interfaces are retained for the time being for backwards compatibility.

The ErrorListener class as defined in JAXP has a number of disadvantages:

• All errors and warnings are reported as Exception objects, which are very expensive to construct and occupy a lot of memory; exceptions are not appropiate for holding error information unless the exception is actually thrown.
• The exceptions are instances of the JAXP TransformerException class, which links them to XSLT and makes it clumsy to reuse the mechanism for use outside XSLT.
• The distinction between the warning(), error(), and fatalError() callbacks has never been entirely clear; it is motivated by distinctions in the XSLT 1.0 specification that have changed in subsequent versions of XSLT, and have never related clearly to errors in other contexts such as schema validation.
• The ErrorListener methods are allowed to throw a checked exception, but the effect of doing so has never been very well defined. The fact that they can throw checked exceptions has a pervasive effect; it means that any method within Saxon that issues a warning has to declare that it is capable of throwing an exception, and this cascades to its callers. In the past Saxon has used an UnfailingErrorListener internally to limit the damage, but this only complicates the design.
• Generally, a processing task (such as an XSLT compilation episode, or an XSLT execution) will make a sequence of calls to an ErrorListener and to be useful, different concurrent tasks need to write their messages to different ErrorListeners so that the output messages can be distinguished. This makes APIs that set an ErrorListener on a shared object (such as the Saxon Configuration or the JAXP TransformerFactory) troublesome as regards thread safety. For the JAXP TransformerFactory this has been addressed by making the newTemplates() method synchronised; it is therefore no longer possible for two concurrent stylesheet compilations to interleave their error messages to the same ErrorListener. At the Saxon Configuration level it is no longer possible to set an ErrorListener as a configuration property.

The replacement ErrorReporter interface has a single method (report), and is defined as a Java FunctionalInterface, which makes it convenient to supply an ErrorReporter in the form of a lambda expression. The object passed to the report() method (in general, an XmlProcessingError) is not itself an exception (though in some cases it may wrap an exception), which means that Saxon does not have to create exception objects unnecessarily. The report() method throws no checked exceptions. The severity of the error (warning, error, or fatal) is defined as a property of the error object, rather than being distinguished by calling different methods of the error handler. The error handler is allowed to upgrade the severity of the error.

Interfaces at the s9api level continue to accept an ErrorListener for backwards compatibility, but the methods have been deprecated. Interfaces deeper in the Saxon internals have dropped support for the ErrorListener.

In previous releases, although it was not documented, an ErrorListener that was set on the XsltCompiler was inherited by any XsltTransformer or Xslt30Transformer created from that XsltCompiler. This is no longer the case (and the same is true if an ErrorList or ErrorReporter is provided).

XPathCompiler

A new method is added for XPathCompiler: addXsltFunctionLibrary(). This takes an XsltPackage as argument, representing a compiled XSLT 3.0 library package. The global public functions in the package (those declared using <xsl:function visibility='public'>) become available for calling from XPath expressions compiled using this XPathCompiler.