net.sf.saxon.s9api

Class XPathSelector

java.lang.Object

net.sf.saxon.s9api.XPathSelector

All Implemented Interfaces:

Iterable<XdmItem>

public class XPathSelector
extends Object
implements Iterable<XdmItem>

An XPathSelector represents a compiled and loaded XPath expression ready for execution. The XPathSelector holds details of the dynamic evaluation context for the XPath expression.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	XPathSelector(XPathExpression exp, Map<StructuredQName,XPathVariable> declaredVariables)

Method Summary

Methods

Modifier and Type	Method and Description
boolean	effectiveBooleanValue() Evaluate the XPath expression, returning the effective boolean value of the result.
XdmValue	evaluate() Evaluate the expression, returning the result as an XdmValue (that is, a sequence of nodes and/or atomic values).
XdmItem	evaluateSingle() Evaluate the XPath expression, returning the result as an XdmItem (that is, a single node or atomic value).
XdmItem	getContextItem() Get the context item used for evaluating the XPath expression.
XPathDynamicContext	getUnderlyingXPathContext() Get the underlying dynamic context object.
URIResolver	getURIResolver() Get the URI resolver.
Iterator<XdmItem>	iterator() Evaluate the expression, returning the result as an Iterator (that is, an iterator over a sequence of nodes and/or atomic values).
void	setContextItem(XdmItem item) Set the context item for evaluating the XPath expression.
void	setURIResolver(URIResolver resolver) Set an object that will be used to resolve URIs used in fn:doc() and related functions.
void	setVariable(QName name, XdmValue value) Set the value of a variable

Methods inherited from class java.lang.Object

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

Constructor Detail

XPathSelector

protected XPathSelector(XPathExpression exp,
             Map<StructuredQName,XPathVariable> declaredVariables)

Method Detail

setContextItem

public void setContextItem(XdmItem item)
                    throws SaxonApiException

Set the context item for evaluating the XPath expression. This may be either a node or an atomic value. Most commonly it will be a document node, which might be constructed using the DocumentBuilder.build(javax.xml.transform.Source) method.

Parameters:

item - The context item for evaluating the expression. Must not be null.

Throws:

SaxonApiException - if an error occurs, for example because the type of item supplied does not match the required item type

getContextItem

public XdmItem getContextItem()

Get the context item used for evaluating the XPath expression. This may be either a node or an atomic value. Most commonly it will be a document node, which might be constructed using the Build method of the DocumentBuilder object.

Returns:

The context item for evaluating the expression, or null if no context item has been set.

setVariable

public void setVariable(QName name,
               XdmValue value)
                 throws SaxonApiException

Set the value of a variable

Parameters:

name - The name of the variable. This must match the name of a variable that was declared to the XPathCompiler. No error occurs if the expression does not actually reference a variable with this name.

value - The value to be given to the variable.

Throws:

SaxonApiException - if the variable has not been declared or if the type of the value supplied does not conform to the required type that was specified when the variable was declared

setURIResolver

public void setURIResolver(URIResolver resolver)

Set an object that will be used to resolve URIs used in fn:doc() and related functions.

Parameters:

resolver - An object that implements the URIResolver interface, or null.

Since:

9.4

getURIResolver

public URIResolver getURIResolver()

Get the URI resolver.

Returns:

the user-supplied URI resolver if there is one, or the system-defined one otherwise

Since:

9.4

evaluate

public XdmValue evaluate()
                  throws SaxonApiException

Evaluate the expression, returning the result as an XdmValue (that is, a sequence of nodes and/or atomic values).

Note: Although a singleton result may be represented as an XdmItem, there is no guarantee that this will always be the case. If you know that the expression will return at most one node or atomic value, it is best to use the evaluateSingle method, which does guarantee that an XdmItem (or null) will be returned.

Returns:

An XdmValue representing the results of the expression.

Throws:

SaxonApiException - if a dynamic error occurs during the expression evaluation.

evaluateSingle

public XdmItem evaluateSingle()
                       throws SaxonApiException

Evaluate the XPath expression, returning the result as an XdmItem (that is, a single node or atomic value).

Returns:

an XdmItem representing the result of the expression, or null if the expression returns an empty sequence. If the expression returns a sequence of more than one item, any items after the first are ignored.

Throws:

SaxonApiException - if a dynamic error occurs during the expression evaluation.

iterator

public Iterator<XdmItem> iterator()
                           throws SaxonApiUncheckedException

Evaluate the expression, returning the result as an Iterator (that is, an iterator over a sequence of nodes and/or atomic values).

Because an XPathSelector is an Iterable, it is possible to iterate over the result using a Java 5 "for each" expression, for example:

 XPathCompiler compiler = processor.newXPathCompiler();
 XPathSelector seq = compiler.compile("1 to 20").load();
 for (XdmItem item : seq) {
   System.err.println(item);
 }
 

Specified by:

iterator in interface Iterable<XdmItem>

Returns:

An iterator over the sequence that represents the results of the expression. Each object in this sequence will be an instance of XdmItem. Note that the expression may be evaluated lazily, which means that a successful response from this method does not imply that the expression has executed successfully: failures may be reported later while retrieving items from the iterator.

Throws:

SaxonApiUncheckedException - if a dynamic error occurs during XPath evaluation that can be detected at this point. It is also possible that an SaxonApiUncheckedException will be thrown by the hasNext() method of the returned iterator.

effectiveBooleanValue

public boolean effectiveBooleanValue()
                              throws SaxonApiException

Evaluate the XPath expression, returning the effective boolean value of the result.

Returns:

a boolean representing the effective boolean value of the result of evaluating the expression, as defined by the rules for the fn:boolean() function.

Throws:

SaxonApiException - if a dynamic error occurs during the expression evaluation, or if the result of the expression is a value whose effective boolean value is not defined (for example, a date or a sequence of three integers)

Since:

9.1

getUnderlyingXPathContext

public XPathDynamicContext getUnderlyingXPathContext()

Get the underlying dynamic context object. This provides an escape hatch to the underlying implementation classes, which contain methods that may change from one release to another.

Returns:

the underlying object representing the dynamic context for query execution