net.sf.saxon.xpath

Class XPathEvaluator

java.lang.Object

net.sf.saxon.xpath.XPathEvaluator

All Implemented Interfaces:

XPath

public class XPathEvaluator
extends Object
implements XPath

XPathEvaluator implements the JAXP 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.

Author:

Michael H. Kay

Constructor Summary

Constructors

Constructor and Description
XPathEvaluator() Default constructor.
XPathEvaluator(Configuration config) Construct an XPathEvaluator with a specified configuration.

Method Summary

Methods

Modifier and Type	Method and Description
XPathExpression	compile(String expr) Compile an XPath 2.0 expression
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	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, Object node) Single-shot method to compile an execute an XPath 2.0 expression, returning the result as a string.
Object	evaluate(String expr, Object node, QName qName) Single-shot method to compile and execute an XPath 2.0 expression.
Configuration	getConfiguration() Get the Configuration used by this XPathEvaluator
NamespaceContext	getNamespaceContext() Get the namespace context, if one has been set using setNamespaceContext(javax.xml.namespace.NamespaceContext)
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.
void	reset()
void	setNamespaceContext(NamespaceContext namespaceContext) Set the namespace context to be used.
void	setXPathFunctionResolver(XPathFunctionResolver xPathFunctionResolver) Set the resolver for XPath functions
void	setXPathVariableResolver(XPathVariableResolver xPathVariableResolver) Set the resolver for XPath variables

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

XPathEvaluator

public XPathEvaluator()

Default constructor. Creates an XPathEvaluator with Configuration appropriate to the version of the Saxon software being run.

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 an EnterpriseConfiguration.

Method Detail

getConfiguration

public Configuration getConfiguration()

Get the Configuration used by this XPathEvaluator

Returns:

the Configuration used by this XPathEvaluator

getStaticContext

public JAXPXPathStaticContext getStaticContext()

Get the current static context. The caller can set properties of the returned static context to influence the way in which XPath expressions are compiled and evaluated; for example it is possible to set whether XPath 1.0 backwards compatibility is enabled or not.

Returns:

the static context

reset

public void reset()

Specified by:

reset in interface XPath

setXPathVariableResolver

public void setXPathVariableResolver(XPathVariableResolver xPathVariableResolver)

Set the resolver for XPath variables

Specified by:

setXPathVariableResolver in interface XPath

Parameters:

xPathVariableResolver - a resolver for variables

getXPathVariableResolver

public XPathVariableResolver getXPathVariableResolver()

Get the resolver for XPath variables

Specified by:

getXPathVariableResolver in interface XPath

Returns:

the resolver, if one has been set

setXPathFunctionResolver

public void setXPathFunctionResolver(XPathFunctionResolver xPathFunctionResolver)

Set the resolver for XPath functions

Specified by:

setXPathFunctionResolver in interface XPath

Parameters:

xPathFunctionResolver - a resolver for XPath function calls

getXPathFunctionResolver

public XPathFunctionResolver getXPathFunctionResolver()

Get the resolver for XPath functions

Specified by:

getXPathFunctionResolver in interface XPath

Returns:

the resolver, if one has been set

setNamespaceContext

public void setNamespaceContext(NamespaceContext namespaceContext)

Set the namespace context to be used.

Specified by:

setNamespaceContext in interface XPath

Parameters:

namespaceContext - The namespace context

getNamespaceContext

public NamespaceContext getNamespaceContext()

Get the namespace context, if one has been set using setNamespaceContext(javax.xml.namespace.NamespaceContext)

Specified by:

getNamespaceContext in interface XPath

Returns:

the namespace context if set, or null otherwise

importSchema

public void importSchema(Source source)
                  throws SchemaException

Import a schema. This is possible only if Saxon-EE is being used, and if the Configuration is an EnterpriseConfiguration. 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 invalid

UnsupportedOperationException - if the configuration is not schema-aware

compile

public XPathExpression compile(String expr)
                        throws XPathExpressionException

Compile an XPath 2.0 expression

Specified by:

compile in interface XPath

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.

evaluate

public Object evaluate(String expr,
              Object node,
              QName qName)
                throws XPathExpressionException

Single-shot method to compile and execute an XPath 2.0 expression.

Specified by:

evaluate in interface XPath

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 XPath 2.0 allows the context item to be "absent" (null). So Saxon executes the XPath expression with the context item undefined.

qName - The type of result required. For details, see XPathExpressionImpl.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:

XPathExpressionException - if any static or dynamic error occurs in evaluating the expression.

evaluate

public String evaluate(String expr,
              Object node)
                throws XPathExpressionException

Single-shot method to compile an execute an XPath 2.0 expression, returning the result as a string.

Specified by:

evaluate in interface XPath

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 XPath 2.0 allows the context item to be "absent" (null). So Saxon 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.

evaluate

public Object evaluate(String expr,
              InputSource inputSource,
              QName qName)
                throws 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 interface XPath

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.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:

XPathExpressionException - if any static or dynamic error occurs in evaluating the expression.

NullPointerException - if any of the three arguments is null

evaluate

public String evaluate(String expr,
              InputSource inputSource)
                throws 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 interface XPath

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