Saxon: the XPath API

This document describes how to use Saxon as a Java class library, without making any use of XSLT stylesheets. If you want to know how to control stylesheet processing from a Java application, see using-xsl.html.

The first section below describes Saxon's XPath API. This allows a Java application to execute XPath expressions against a source document, and manipulate the results. No stylesheet is involved.

Subsequent sections describe more intimate APIs that are available in Saxon.

In addition to the APIs described here, Saxon's JavaDoc documentation describes all the public classes and methods that are available for advanced users. These are all subject to change from one release to the next.

A new API has been introduced for executing XPath expressions. The API is loosely modelled on the proposed DOM Level 3 API for XPath. For full documentation, see the Javadoc description of package net.sf.saxon.xpath. A sample application using this API is available: it is called XPathExample.java, and can be found in the samples/java directory. To run this application, see the instructions in samples.html.

This API is based on the class net.sf.saxon.xpath.XPathEvaluator. This class provides a few simple configuration interfaces to set the source document, the static context, and the context node, plus a number of methods for evaluating XPath expressions.

The XPathEvaluator must be initialized with a source document, which can be supplied as a JAXP Source object. Any kind of Source object recognized by Saxon is allowed (including, for example, a JDOM source). This can be supplied either in the constructor for the XPathEvaluator, or through the setSource method. The setSource method returns a net.sf.saxon.om.DocumentInfo object representing the root of the tree for the document: this is useful if you want to use some of the more advanced features of the Saxon API, but you can ignore it if you don't need it.

There are two methods for direct evaluation of XPath expressions, evaluate() which returns a List containing the result of the expression (which in general is a sequence), and evaluateSingle() which returns the first item in the result (this is appropriate where it is known that the result will be single-valued). The results are returned as NodeInfo objects in the case of nodes, or as objects of the most appropriate Java class in the case of atomic values: for example, Boolean, Double, or String in the case of the traditional XPath 1.0 data types.

XPath itself provides no sorting capability. You can therefore specify a sort order in which you want the results of an expression returned. This is done by nominating another expression, via the setSortKey method: this second expression is applied to each item in the result sequence, and its value determines the position of that item in the sorted result order.

You can call methods directly on the NodeInfo object to get information about a node: for example getDisplayName() gets the name of the node in a form suitable for display, and getStringValue() gets the string value of the node, as defined in the XPath data model. You can also use the node as the context node for evaluation of subsequent expressions, by calling the method setContextNode on the XPathEvaluator object.

It is also possible to prepare an XPath expression for subsequent execution, using the createExpression() method on the XPathEvaluator class. This is worthwhile where the same expression is to be executed repeatedly. The compiled expression is represented by an instance of the class net.sf.saxon.xpath.XPathExpression, and it can be executed repeatedly, with different context nodes. However, the compiled expression is bound to one particular source document (this is to ensure that the same NamePool is used).

A compiled expression can reference XPath variables; the values of these variables must be supplied before the expression is evaluated, and can be different each time it is evaluated. To do this you will need access to the StandaloneContext object used by the XPathEvaluator: you can get this by calling getStaticContext and casting the result to a StandaloneContext. Before compiling an expression that uses variables, the variables it uses must be declared using the declareVariable() method on the StandaloneContext class. This method returns a Variable object, whose setValue() method can be used to set a value for the variable before the expression is evaluated.

The StandaloneContext object is also needed if the XPath expression uses namespaces (which it will need to, if the source document itself uses namespaces). Before compiling or evaluating an XPath expression that uses namespace prefixes, the namespace must be declared. You can do this explicitly using the declareNamespace() method on the StandaloneContext object. Alternatively, you can use the setNamespaces() method, which declares all the namespaces that are in-scope for a given node in the source document. Certain namespaces are predeclared with their conventional prefixes: the XSLT namespace (xsl), the XML namespace (xml), the XML Schema namespace (xs), and the Saxon namespace (saxon).

All the core XPath functions are available, with the exception of the document function. The XSLT-specific functions, such as key and generate-id, are not available. You can call Java extension functions by binding a namespace to the Java class (for example, java:java.lang.Double). You can also call Saxon and EXSLT extension functions using their normal namespace - with the exception of a small number of Saxon extension functions, such as saxon:evaluate and saxon:serialize, which work only in an XSLT context.

The design principle of this API is to minimize the number of Saxon classes that need to be used. Apart from the NodeInfo interface, which is needed when manipulating Saxon trees, only the four classes XPathProcessor, XPathExpression, StandaloneContext, and XPathException are needed. For convenience, these classes are all in the net.sf.saxon.xpath package.

The NodeInfo object represents a node of an XML document. It has a subclass DocumentInfo to represent the root node, but all other nodes are represented by NodeInfo itself. These follow the XPath data model closely.

In earlier releases, NodeInfo extended the DOM interface Node. This is no longer the case; it was changed to make it easier to integrate Saxon with other XML tree representations such as JDOM. However, the main Saxon implementations of the NodeInfo interface continue to also implement the DOM Node interface, so you can still use DOM methods by casting the concrete node object to a DOM class.

The NodeInfo object provides the application with information about the node. The most commonly-used methods include:

The first thing the application must do is to build the source document, in the form of a tree. The simplest approach is to use the sequence:

String systemId = new File(sourceFile).toURL().toString(); DocumentInfo doc = new XPathEvaluator().setSource( new SAXSource(new InputSource(systemId)));

Alternatively, you can use the JAXP 1.1 interface. For example:

System.setProperty("javax.xml.parsers.DocumentBuilderFactory", "net.sf.saxon.om.DocumentBuilderFactoryImpl"); DocumentBuilderFactory dfactory = DocumentBuilderFactory.newInstance(); dfactory.setNamespaceAware(true); DocumentBuilder docBuilder = dfactory.newDocumentBuilder(); String systemId = new File(sourceFile).toURL().toString(); Node doc = docBuilder.parse(new InputSource(systemId));

You can define the parser to be used by supplying a parser within the SAXSource object supplied to the Builder.build() method. If you don't supply a parser, Saxon will select one using the JAXP mechanisms, specifically, the system property javax.xml.parsers.DocumentBuilderFactory.

If you want to use different parsers depending on the URI of the document being read, you can achieve this by writing a URIResolver that nominates the parser to be used for each input file.

The ability to register node handlers with the Controller is withdrawn at this release.

Michael H. Kay
28 April 2003