net.sf.saxon.xpath
public class XPathEvaluator extends Object implements 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 Saxon Configuration
object. By default a new Configuration
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 the Configuration
used by this evaluator.
Constructor Summary | |
---|---|
XPathEvaluator()
Default constructor. | |
XPathEvaluator(Configuration config)
Construct an XPathEvaluator with a specified configuration. | |
XPathEvaluator(Source source)
Construct an XPathEvaluator to process a particular source document. |
Method Summary | |
---|---|
XPathExpression | compile(String expr)
Compile an XPath 2.0 expression |
XPathExpressionImpl | createExpression(String expression)
Prepare an XPath expression for subsequent evaluation. |
List | evaluate(String expression)
Prepare and execute an XPath expression, supplied as a string, and returning the results
as a List. |
Object | evaluate(String expr, Object node, QName qName)
Single-shot method to compile and execute an XPath 2.0 expression. |
String | evaluate(String expr, Object node)
Single-shot method to compile an execute an XPath 2.0 expression, returning
the result as a string. |
Object | evaluate(String expr, InputSource inputSource, QName qName)
Single-shot method to parse and build a source document, and
compile an execute an XPath 2.0 expression, against that document |
String | evaluate(String expr, 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 string |
Object | evaluateSingle(String expression)
Prepare and execute an XPath expression, supplied as a string, and returning the first
item in the result. |
Configuration | getConfiguration()
Get the Configuration used by this XPathEvaluator |
Executable | getExecutable()
Get the executable |
NamespaceContext | getNamespaceContext()
Get the namespace context, if one has been set using |
JAXPXPathStaticContext | getStaticContext()
Get the current static context |
XPathFunctionResolver | getXPathFunctionResolver()
Get the resolver for XPath functions |
XPathVariableResolver | getXPathVariableResolver()
Get the resolver for XPath variables |
void | importSchema(Source source)
Import a schema. |
boolean | isBackwardsCompatible()
Get the value of XPath 1.0 compatibility mode |
static void | main(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)
Set the context node. |
void | setNamespaceContext(NamespaceContext namespaceContext)
Set the namespace context to be used. |
NodeInfo | setSource(Source source)
Supply a document against which XPath expressions are to be executed, converting it to a
Saxon NodeInfo object.
|
void | setStaticContext(JAXPXPathStaticContext context)
Set the static context for compiling XPath expressions. |
void | setStripSpace(boolean strip)
Indicate whether all whitespace text nodes in the source document are to be
removed. |
void | setXPathFunctionResolver(XPathFunctionResolver xPathFunctionResolver)
Set the resolver for XPath functions |
void | setXPathVariableResolver(XPathVariableResolver xPathVariableResolver)
Set the resolver for XPath variables |
Parameters: config the configuration to be used. If schema-aware XPath expressions are to be used, this must be an EnterpriseConfiguration.
Parameters: source The source document (or a specific node within it).
Parameters: expr the XPath 2.0 expression to be compiled, as a string
Returns: the compiled form of the expression
Throws: 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.
Deprecated: since Saxon 8.9 - use compile
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: net.sf.saxon.trans.XPathException if the syntax of the expression is wrong, or if it references namespaces, variables, or functions that have not been declared.
Deprecated: since Saxon 8.9 - use the various method defined in the JAXP interface definition
Prepare 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:
Parameters: expr The XPath 2.0 expression to be compiled and executed node 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 XPathEvaluator method if available, and if none
is available, executes the XPath expression with the context item undefined.
Returns: the result of evaluating the expression, returned as described in XPathExpressionImpl
Throws: XPathExpressionException if any static or dynamic error occurs in evaluating the expression.
Parameters: expr The XPath 2.0 expression to be compiled and executed node 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 XPathEvaluator 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: XPathExpressionException if any static or dynamic error occurs in evaluating the expression.
Parameters: expr The XPath 2.0 expression to be compiled and executed inputSource 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, see XPathExpressionImpl
Returns: the result of evaluating the expression, returned as described in XPathExpressionImpl
Throws: XPathExpressionException if any static or dynamic error occurs in evaluating the expression. NullPointerException if any of the three arguments is null
Parameters: expr The XPath 2.0 expression to be compiled and executed inputSource 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: XPathExpressionException if any static or dynamic error occurs in evaluating the expression. NullPointerException if either of the two arguments is null
Deprecated: since Saxon 8.9 - use the methods defined in the JAXP interface
Prepare 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
Returns: the Configuration used by this XPathEvaluator
Returns: the executable
Returns: the namespace context if set, or null otherwise
Returns: the static context
Returns: the resolver, if one has been set
Returns: the resolver, if one has been set
Parameters: source A Source object identifying the schema document to be loaded
Throws: net.sf.saxon.type.SchemaException if the schema contained in this document is invalid UnsupportedOperationException if the configuration is not schema-aware
Returns: true if XPath 1.0 compatibility mode is set
Parameters: args command line arguments. First parameter is the filename containing the source document, second parameter is the XPath expression.
Parameters: compatible true if XPath 1.0 compatibility mode is to be set to true, false if it is to be set to false.
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 argument
Set 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 Saxon Configuration as used by this XPathEvaluator.
Throws: IllegalArgumentException if the supplied node was built using the wrong Configuration
Parameters: namespaceContext The namespace context
If the supplied source is a NodeInfo
, it is returned unchanged.
If the supplied source is a DOMSource
, the result is a Saxon NodeInfo
wrapper around the DOM Node contained by the DOMSource.
In all other cases, the result is a document node, and is the same as the result of calling Configuration with the same argument; except that when whitespace stripping has been requested using XPathEvaluator, this request is passed on.
Despite the name of this method, it does not change the state of the XPathEvaluator
in any way.
Parameters: source Any javax.xml.transform.Source object representing the document against
which XPath expressions will be executed. Note that a Saxon 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. DocumentInfo
(indeed any NodeInfo
)
can be used as a Source. To use a third-party DOM Document as a source, create an instance of
javax.xml.transform.dom.DOMSource DOMSource
to wrap it.
Returns: the NodeInfo of the start node in the resulting document object.
Throws: XPathException if the supplied Source is a NodeInfo object that was built using an incompatible Configuration (that is, a Configuration using a different NamePool). Also, if any error occurs parsing the document supplied as the Source.
Parameters: context the static context
Throws: IllegalArgumentException if the supplied static context uses a different and incompatible Configuration from the one used in this XPathEvaluator
Deprecated: since 8.9. The preferred way to define options for the way in which source documents are built is to use the class AugmentedSource for any of the methods expecting a Source 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.
Parameters: xPathFunctionResolver a resolver for XPath function calls
Parameters: xPathVariableResolver a resolver for variables