Saxon provides an API for executing XPath expressions. The API is an implementation of the JAXP 1.3
XPath API, which in turn is loosely modelled
on the DOM Level 3 API for XPath (which Saxon does not implement).
For full documentation, see the Javadoc description of package
net.sf.saxon.xpath
. Two sample applications using this API are available: they are called
XPathExample.java
and ApplyXPathJAXP.java
,
and can be found in the samples/java
directory.
The XPathExample.java
application has been rewritten in Saxon 8.2
to use JAXP 1.3 interfaces. To run this application, see the instructions
in Shakespeare XPath Sample Application.
The ApplyXPathJAXP.java
application is an enhanced version of the class of the
same name issued as a sample application in the JAXP 1.3 distribution. It has been enhanced to show
the use of more advanced features, such as the ability to bind namespaces, variables, and functions, and
also to demonstrate use of the XPath API with different object models.
Because the XPath API in Saxon predates the introduction of the JAXP 1.3 XPath API, there is often more than one way of achieving the same effect. It is likely that in time, some of the native Saxon methods will be deprecated and replaced by the standard JAXP methods.
An application using the JAXP 1.3 XPath API starts by instantiating a factory class. This is done by calling:
XPathFactory xpathFactory = XPathFactory.newInstance(objectModel);
XPath xpath = xpathFactory.newXPath();
Here objectModel
is a URI that identifies the object model you are using. Saxon recognizes
four values for the object model:
Symbolic name |
Meaning |
XPathConstants.DOM_OBJECT_MODEL |
The DOM object model |
NamespaceConstant.OBJECT_MODEL_SAXON |
Saxon's native object model.
This means anything that implements the |
NamespaceConstant.OBJECT_MODEL_JDOM |
The JDOM object model |
NamespaceConstant.OBJECT_MODEL_XOM |
The XOM object model |
To ensure that Saxon is selected as your XPath implementation, you must specify one of these
constants as your chosen object model, and you must ensure that the Java system property
javax.xml.xpath.XPathFactory
is set to the value net.sf.saxon.xpath.XPathFactoryImpl
.
Normally, if Saxon is on your classpath then the Saxon XPath implementation will be picked up automatically, but
if there are other implementations on the classpath as well then it is best to set the system property
explicitly to be sure.
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 XPath
object returned from the above calls allows you to set the static context for
evaluating XPath expressions (you can pre-declare namespaces, variables, and functions), and to compile
XPath expressions in this context. A compiled XPath expression (an object of class XPathExpression
)
can then be evaluated, with a supplied node (represented by a class in the selected object model) supplied
as the context node. For further details, see the Javadoc specifications and the supplied example applications.
The JAXP specification leaves it rather up to the implementation how the results of an XPath expression will be returned. This is partly because it is defined only for XPath 1.0, which has a much simpler type system, and partly because it is deliberately designed to be independent of the object model used to represent XML trees.
If you specify the return type XPathConstants.BOOLEAN
then Saxon will return the effective
boolean value of the expression, as a java.lang.Boolean
. This is the same as wrapping the expression
in a call of the XPath boolean()
function.
If you specify the return type XPathConstants.STRING
then Saxon will return the result
of the expression converted to a string, as a java.lang.Boolean
.
This is the same as wrapping the expression in a call of the XPath string()
function.
If you specify the return type XPathConstants.NUMBER
then Saxon will return the result
of the expression converted to a double as a java.lang.Double
.
This is the same as wrapping the expression in a call of the XPath number()
function.
If you specify the return type XPathConstants.NODE
then Saxon will return the result
the result as a node object in the selected object model. With the DOM model this will be an instance
of org.w3.dom.Node
, with the native Saxon model it will be an instance of net.sf.saxon.om.NodeInfo
,
and so on.
If the return type is XPathConstants.NODESET
, the result will be a Java List
containing node objects in the selected object model. Note that the DOM NodeList
class is not
returned.
Saxon does not recognize additional values for the return type other than the values defined in JAXP. If you want to return a different result type, for example a list of integers or a date, use one of the methods in which the result type is unspecified. If any conversions are necessary, do them within the XPath expression itself, using casts or constructor functions. The Java object that is returned will be a representation of the XPath value, converted in the same way as arguments to a extension functions.
Saxon's implementation of XPathExpression
(namely net.sf.saxon.xpath.XPathExpressionImpl
)
provides additional methods for evaluating the XPath expression. In particular the rawIterator()
method with no arguments returns a Saxon SequenceIterator
which allows the application to process
the results of any XPath expression, with no conversion: all values will be represented using a native Saxon class,
for example a node will be represented as a NodeInfo
and a QName as a QNameValue
.
The NodeInfo
interface is described in the next section.
The native Saxon methods rely on the dynamic context being established using separate setXX()
calls on the XPathExpressionImpl
object. If these methods are used, the XPathExpression
object will not be thread-safe.
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.