Class XPathEvaluator
- java.lang.Object
-
- net.sf.saxon.xpath.XPathEvaluator
-
- All Implemented Interfaces:
javax.xml.xpath.XPath
public class XPathEvaluator extends java.lang.Object implements javax.xml.xpath.XPath
XPathEvaluator provides a simple API for standalone XPath processing (that is, executing XPath expressions in the absence of an XSLT stylesheet). It is an implementation of the JAXP 1.3 XPath interface, with additional methods provided (a) for backwards compatibility (b) to give extra control over the XPath evaluation, and (c) to support XPath 2.0.
It is intended to evolve this so that it only supports the JAXP style of operation. Some of the methods are therefore marked as deprecated in this release, and will be dropped in a future release.
For an alternative XPath API, offering more direct access to Saxon capabilities, see
XPathEvaluator
.Note that the
XPathEvaluator
links to a SaxonConfiguration
object. By default a newConfiguration
is created automatically. In many applications, however, it is desirable to share a configuration. The default configuration is not schema aware. All source documents used by XPath expressions under this evaluator must themselves be built using theConfiguration
used by this evaluator.- Author:
- Michael H. Kay
-
-
Constructor Summary
Constructors Constructor Description XPathEvaluator()
Default constructor.XPathEvaluator(javax.xml.transform.Source source)
Construct an XPathEvaluator to process a particular source document.XPathEvaluator(Configuration config)
Construct an XPathEvaluator with a specified configuration.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description javax.xml.xpath.XPathExpression
compile(java.lang.String expr)
Compile an XPath 2.0 expressionXPathExpressionImpl
createExpression(java.lang.String expression)
Deprecated.since Saxon 8.9 - usecompile(String)
java.util.List
evaluate(java.lang.String expression)
Deprecated.since Saxon 8.9 - use the various method defined in the JAXP interface definitionjava.lang.String
evaluate(java.lang.String expr, java.lang.Object node)
Single-shot method to compile an execute an XPath 2.0 expression, returning the result as a string.java.lang.Object
evaluate(java.lang.String expr, java.lang.Object node, javax.xml.namespace.QName qName)
Single-shot method to compile and execute an XPath 2.0 expression.java.lang.String
evaluate(java.lang.String expr, org.xml.sax.InputSource inputSource)
Single-shot method to parse and build a source document, and compile an execute an XPath 2.0 expression, against that document, returning the result as a stringjava.lang.Object
evaluate(java.lang.String expr, org.xml.sax.InputSource inputSource, javax.xml.namespace.QName qName)
Single-shot method to parse and build a source document, and compile an execute an XPath 2.0 expression, against that documentjava.lang.Object
evaluateSingle(java.lang.String expression)
Deprecated.since Saxon 8.9 - use the methods defined in the JAXP interfaceConfiguration
getConfiguration()
Get the Configuration used by this XPathEvaluatorExecutable
getExecutable()
Get the executablejavax.xml.namespace.NamespaceContext
getNamespaceContext()
Get the namespace context, if one has been set usingsetNamespaceContext(javax.xml.namespace.NamespaceContext)
JAXPXPathStaticContext
getStaticContext()
Get the current static contextjavax.xml.xpath.XPathFunctionResolver
getXPathFunctionResolver()
Get the resolver for XPath functionsjavax.xml.xpath.XPathVariableResolver
getXPathVariableResolver()
Get the resolver for XPath variablesvoid
importSchema(javax.xml.transform.Source source)
Import a schema.boolean
isBackwardsCompatible()
Get the value of XPath 1.0 compatibility modestatic void
main(java.lang.String[] args)
A simple command-line interface for the XPathEvaluator (not documented).void
reset()
void
setBackwardsCompatible(boolean compatible)
Set XPath 1.0 compatibility mode on or off (by default, it is false).void
setContextNode(NodeInfo node)
Deprecated.since Saxon 8.9 - use the various method defined in the JAXP interface definition, which allow a NodeInfo object to be supplied as the value of the Source argumentvoid
setNamespaceContext(javax.xml.namespace.NamespaceContext namespaceContext)
Set the namespace context to be used.NodeInfo
setSource(javax.xml.transform.Source source)
Supply the document against which XPath expressions are to be executed.void
setStaticContext(JAXPXPathStaticContext context)
Set the static context for compiling XPath expressions.void
setStripSpace(boolean strip)
Deprecated.since 8.9.void
setXPathFunctionResolver(javax.xml.xpath.XPathFunctionResolver xPathFunctionResolver)
Set the resolver for XPath functionsvoid
setXPathVariableResolver(javax.xml.xpath.XPathVariableResolver xPathVariableResolver)
Set the resolver for XPath variables
-
-
-
Constructor Detail
-
XPathEvaluator
public XPathEvaluator()
Default constructor. Creates an XPathEvaluator with a default configuration and name pool. The default Configuration is not schema-aware.
-
XPathEvaluator
public XPathEvaluator(Configuration config)
Construct an XPathEvaluator with a specified configuration.- Parameters:
config
- the configuration to be used. If schema-aware XPath expressions are to be used, this must be a SchemaAwareConfiguration.
-
XPathEvaluator
public XPathEvaluator(javax.xml.transform.Source source) throws XPathException
Construct an XPathEvaluator to process a particular source document. This is equivalent to using the default constructor and immediately calling setSource().- Parameters:
source
- The source document (or a specific node within it).- Throws:
XPathException
-
-
Method Detail
-
getConfiguration
public Configuration getConfiguration()
Get the Configuration used by this XPathEvaluator- Returns:
- the Configuration used by this XPathEvaluator
-
setStripSpace
public void setStripSpace(boolean strip)
Deprecated.since 8.9. The preferred way to define options for the way in which source documents are built is to use the classAugmentedSource
for any of the methods expecting aSource
object.Indicate whether all whitespace text nodes in the source document are to be removed. This option has no effect unless it is called before the call on setSource(), and unless the Source supplied to setSource() is a SAXSource or StreamSource.- Parameters:
strip
- True if all whitespace text nodes are to be stripped from the source document, false otherwise. The default if the method is not called is false.
-
setSource
public NodeInfo setSource(javax.xml.transform.Source source) throws XPathException
Supply the document against which XPath expressions are to be executed. This method must be called before preparing or executing an XPath expression. Setting a new source document clears all the namespaces that have been declared.- Parameters:
source
- Any javax.xml.transform.Source object representing the document against which XPath expressions will be executed. Note that a SaxonDocumentInfo
(indeed anyNodeInfo
) can be used as a Source. To use a third-party DOM Document as a source, create an instance ofDOMSource
to wrap it.The Source object supplied also determines the initial setting of the context item. In most cases the context node will be the root of the supplied document; however, if a NodeInfo or DOMSource is supplied it can be any node in the document.
- Returns:
- the NodeInfo of the start node in the resulting document object.
- Throws:
XPathException
-
setStaticContext
public void setStaticContext(JAXPXPathStaticContext context)
Set the static context for compiling XPath expressions. This provides control over the environment in which the expression is compiled, for example it allows namespace prefixes to be declared, variables to be bound and functions to be defined. For most purposes, the static context can be defined by providing and tailoring an instance of the JAXPXPathStaticContext class. Until this method is called, a default static context is used, in which no namespaces are defined other than the standard ones (xml, xslt, and saxon), and no variables or functions (other than the core XPath functions) are available.- Parameters:
context
- the static context- Throws:
java.lang.IllegalArgumentException
- if the supplied static context uses a different and incompatible Configuration from the one used in this XPathEvaluator
-
getStaticContext
public JAXPXPathStaticContext getStaticContext()
Get the current static context- Returns:
- the static context
-
getExecutable
public Executable getExecutable()
Get the executable- Returns:
- the executable
-
createExpression
public XPathExpressionImpl createExpression(java.lang.String expression) throws XPathException
Deprecated.since Saxon 8.9 - usecompile(String)
Prepare an XPath expression for subsequent evaluation.- Parameters:
expression
- The XPath expression to be evaluated, supplied as a string.- Returns:
- an XPathExpression object representing the prepared expression
- Throws:
XPathException
- if the syntax of the expression is wrong, or if it references namespaces, variables, or functions that have not been declared.
-
setContextNode
public void setContextNode(NodeInfo node)
Deprecated.since Saxon 8.9 - use the various method defined in the JAXP interface definition, which allow a NodeInfo object to be supplied as the value of the Source argumentSet the context node. This provides the context node for any expressions executed after this method is called, including expressions that were prepared before it was called.- Parameters:
node
- The node to be used as the context node. The node must be within a tree built using the same SaxonConfiguration
as used by this XPathEvaluator.- Throws:
java.lang.IllegalArgumentException
- if the supplied node was built using the wrong Configuration
-
evaluate
public java.util.List evaluate(java.lang.String expression) throws XPathException
Deprecated.since Saxon 8.9 - use the various method defined in the JAXP interface definitionPrepare and execute an XPath expression, supplied as a string, and returning the results as a List.- Parameters:
expression
- The XPath expression to be evaluated, supplied as a string.- Returns:
- The results of the expression, as a List. The List represents the sequence
of items returned by the expression. Each item in the list will either be an object
representing a node, or a Java object representing an atomic value.
The types of Java object that may be included in the list, and the XML Schema data types that they
correspond to, are as follows:
- Boolean (xs:boolean)
- String (xs:string)
- BigDecimal (xs:decimal)
- Long (xs:integer and its derived types)
- Double (xs:double)
- Float (xs:float)
- Date (xs:date, xs:dateTime)
- Throws:
XPathException
-
reset
public void reset()
- Specified by:
reset
in interfacejavax.xml.xpath.XPath
-
setBackwardsCompatible
public void setBackwardsCompatible(boolean compatible)
Set XPath 1.0 compatibility mode on or off (by default, it is false). This applies to any XPath expression compiled while this option is in force.- Parameters:
compatible
- true if XPath 1.0 compatibility mode is to be set to true, false if it is to be set to false.
-
isBackwardsCompatible
public boolean isBackwardsCompatible()
Get the value of XPath 1.0 compatibility mode- Returns:
- true if XPath 1.0 compatibility mode is set
-
setXPathVariableResolver
public void setXPathVariableResolver(javax.xml.xpath.XPathVariableResolver xPathVariableResolver)
Set the resolver for XPath variables- Specified by:
setXPathVariableResolver
in interfacejavax.xml.xpath.XPath
- Parameters:
xPathVariableResolver
- a resolver for variables
-
getXPathVariableResolver
public javax.xml.xpath.XPathVariableResolver getXPathVariableResolver()
Get the resolver for XPath variables- Specified by:
getXPathVariableResolver
in interfacejavax.xml.xpath.XPath
- Returns:
- the resolver, if one has been set
-
setXPathFunctionResolver
public void setXPathFunctionResolver(javax.xml.xpath.XPathFunctionResolver xPathFunctionResolver)
Set the resolver for XPath functions- Specified by:
setXPathFunctionResolver
in interfacejavax.xml.xpath.XPath
- Parameters:
xPathFunctionResolver
- a resolver for XPath function calls
-
getXPathFunctionResolver
public javax.xml.xpath.XPathFunctionResolver getXPathFunctionResolver()
Get the resolver for XPath functions- Specified by:
getXPathFunctionResolver
in interfacejavax.xml.xpath.XPath
- Returns:
- the resolver, if one has been set
-
setNamespaceContext
public void setNamespaceContext(javax.xml.namespace.NamespaceContext namespaceContext)
Set the namespace context to be used.- Specified by:
setNamespaceContext
in interfacejavax.xml.xpath.XPath
- Parameters:
namespaceContext
- The namespace context
-
getNamespaceContext
public javax.xml.namespace.NamespaceContext getNamespaceContext()
Get the namespace context, if one has been set usingsetNamespaceContext(javax.xml.namespace.NamespaceContext)
- Specified by:
getNamespaceContext
in interfacejavax.xml.xpath.XPath
- Returns:
- the namespace context if set, or null otherwise
-
importSchema
public void importSchema(javax.xml.transform.Source source) throws SchemaException
Import a schema. This is possible only if the schema-aware version of Saxon is being used, and if the Configuration is a SchemaAwareConfiguration. Having imported a schema, the types defined in that schema become part of the static context.- Parameters:
source
- A Source object identifying the schema document to be loaded- Throws:
SchemaException
- if the schema contained in this document is invalidjava.lang.UnsupportedOperationException
- if the configuration is not schema-aware
-
compile
public javax.xml.xpath.XPathExpression compile(java.lang.String expr) throws javax.xml.xpath.XPathExpressionException
Compile an XPath 2.0 expression- Specified by:
compile
in interfacejavax.xml.xpath.XPath
- Parameters:
expr
- the XPath 2.0 expression to be compiled, as a string- Returns:
- the compiled form of the expression
- Throws:
javax.xml.xpath.XPathExpressionException
- if there are any static errors in the expression. Note that references to undeclared variables are not treated as static errors, because variables are not pre-declared using this API.
-
evaluate
public java.lang.Object evaluate(java.lang.String expr, java.lang.Object node, javax.xml.namespace.QName qName) throws javax.xml.xpath.XPathExpressionException
Single-shot method to compile and execute an XPath 2.0 expression.- Specified by:
evaluate
in interfacejavax.xml.xpath.XPath
- Parameters:
expr
- The XPath 2.0 expression to be compiled and executednode
- The context node for evaluation of the expression.This may be a NodeInfo object, representing a node in Saxon's native implementation of the data model, or it may be a node in any supported external object model: DOM, JDOM, DOM4J, or XOM, or any other model for which support has been configured in the Configuration. Note that the supporting libraries for the chosen model must be on the class path.
Contrary to the interface specification, Saxon does not supply an empty document when the value is null. This is because Saxon supports multiple object models, and it's unclear what kind of document node would be appropriate. Instead, Saxon uses the node supplied to the
setContextNode(net.sf.saxon.om.NodeInfo)
method if available, and if none is available, executes the XPath expression with the context item undefined.qName
- The type of result required. For details, seeXPathExpressionImpl.evaluate(Object, javax.xml.namespace.QName)
- Returns:
- the result of evaluating the expression, returned as described in
XPathExpressionImpl.evaluate(Object, javax.xml.namespace.QName)
- Throws:
javax.xml.xpath.XPathExpressionException
- if any static or dynamic error occurs in evaluating the expression.
-
evaluate
public java.lang.String evaluate(java.lang.String expr, java.lang.Object node) throws javax.xml.xpath.XPathExpressionException
Single-shot method to compile an execute an XPath 2.0 expression, returning the result as a string.- Specified by:
evaluate
in interfacejavax.xml.xpath.XPath
- Parameters:
expr
- The XPath 2.0 expression to be compiled and executednode
- The context node for evaluation of the expressionThis may be a NodeInfo object, representing a node in Saxon's native implementation of the data model, or it may be a node in any supported external object model: DOM, JDOM, DOM4J, or XOM, or any other model for which support has been configured in the Configuration. Note that the supporting libraries for the chosen model must be on the class path.
Contrary to the interface specification, Saxon does not supply an empty document when the value is null. This is because Saxon supports multiple object models, and it's unclear what kind of document node would be appropriate. Instead, Saxon uses the node supplied to the
setContextNode(net.sf.saxon.om.NodeInfo)
method if available, and if none is available, executes the XPath expression with the context item undefined.- Returns:
- the result of evaluating the expression, converted to a string as if by calling the XPath string() function
- Throws:
javax.xml.xpath.XPathExpressionException
- if any static or dynamic error occurs in evaluating the expression.
-
evaluate
public java.lang.Object evaluate(java.lang.String expr, org.xml.sax.InputSource inputSource, javax.xml.namespace.QName qName) throws javax.xml.xpath.XPathExpressionException
Single-shot method to parse and build a source document, and compile an execute an XPath 2.0 expression, against that document- Specified by:
evaluate
in interfacejavax.xml.xpath.XPath
- Parameters:
expr
- The XPath 2.0 expression to be compiled and executedinputSource
- The source document: this will be parsed and built into a tree, and the XPath expression will be executed with the root node of the tree as the context node.qName
- The type of result required. For details, seeXPathExpressionImpl.evaluate(Object, javax.xml.namespace.QName)
- Returns:
- the result of evaluating the expression, returned as described in
XPathExpressionImpl.evaluate(Object, javax.xml.namespace.QName)
- Throws:
javax.xml.xpath.XPathExpressionException
- if any static or dynamic error occurs in evaluating the expression.java.lang.NullPointerException
- if any of the three arguments is null
-
evaluate
public java.lang.String evaluate(java.lang.String expr, org.xml.sax.InputSource inputSource) throws javax.xml.xpath.XPathExpressionException
Single-shot method to parse and build a source document, and compile an execute an XPath 2.0 expression, against that document, returning the result as a string- Specified by:
evaluate
in interfacejavax.xml.xpath.XPath
- Parameters:
expr
- The XPath 2.0 expression to be compiled and executedinputSource
- The source document: this will be parsed and built into a tree, and the XPath expression will be executed with the root node of the tree as the context node- Returns:
- the result of evaluating the expression, converted to a string as if by calling the XPath string() function
- Throws:
javax.xml.xpath.XPathExpressionException
- if any static or dynamic error occurs in evaluating the expression.java.lang.NullPointerException
- if either of the two arguments is null
-
evaluateSingle
public java.lang.Object evaluateSingle(java.lang.String expression) throws XPathException
Deprecated.since Saxon 8.9 - use the methods defined in the JAXP interfacePrepare and execute an XPath expression, supplied as a string, and returning the first item in the result. This is useful where it is known that the expression will only return a singleton value (for example, a single node, or a boolean).- Parameters:
expression
- The XPath expression to be evaluated, supplied as a string.- Returns:
- The first item in the sequence returned by the expression. If the expression returns an empty sequence, this method returns null. Otherwise, it returns the first item in the result sequence, represented as a Java object using the same mapping as for the evaluate() method
- Throws:
XPathException
-
main
public static void main(java.lang.String[] args) throws java.lang.Exception
A simple command-line interface for the XPathEvaluator (not documented).- Parameters:
args
- command line arguments. First parameter is the filename containing the source document, second parameter is the XPath expression.- Throws:
java.lang.Exception
-
-