net.sf.saxon.s9api

Class XQueryEvaluator

Implemented Interfaces:
Iterable

public class XQueryEvaluator
extends java.lang.Object
implements Iterable

An XQueryEvaluator represents a compiled and loaded stylesheet ready for execution. The XQueryEvaluator holds details of the dynamic evaluation context for the stylesheet.

An XQueryEvaluator must not be used concurrently in multiple threads. It is safe, however, to reuse the object within a single thread to run the same stylesheet several times. Running the stylesheet does not change the context that has been established.

An XQueryEvaluator is always constructed by running the Load method of an XQueryExecutable.

An XQueryEvaluator is itself a Iterable. This makes it possible to evaluate the results in a for-each expression.

Constructor Summary

XQueryEvaluator(Processor processor, XQueryExpression expression)
Protected constructor

Method Summary

XdmValue
evaluate()
Perform the query, returning the results as an XdmValue
XdmItem
getContextItem()
Get the initial context item for the query, if one has been set
ErrorListener
getErrorListener()
Get the error listener.
XdmValue
getExternalVariable(QName name)
Get the value that has been set for an external variable
TraceListener
getTraceListener()
Get the registered TraceListener, if any
URIResolver
getURIResolver()
Get the URI resolver.
DynamicQueryContext
getUnderlyingQueryContext()
Get the underlying dynamic context object.
Iterator
iterator()
Get an iterator over the results of the query
void
run()
Perform the query, sending the results to a previously specified destination
void
run(Destination destination)
Perform the query, sending the results to a specified destination
void
setContextItem(XdmItem item)
Set the initial context item for the query
void
setDestination(Destination destination)
Set the destination of the query
void
setErrorListener(ErrorListener listener)
Set the error listener.
void
setExternalVariable(QName name, XdmValue value)
Set the value of external variable defined in the query
void
setSource(Source source)
Set the source document for the query.
void
setTraceListener(TraceListener listener)
Set a TraceListener which will receive messages relating to the evaluation of all expressions.
void
setURIResolver(URIResolver resolver)
Set an object that will be used to resolve URIs used in fn:document() and related functions.

Constructor Details

XQueryEvaluator

protected XQueryEvaluator(Processor processor,
                          XQueryExpression expression)
Protected constructor
Parameters:
expression - the XQuery expression

Method Details

evaluate

public XdmValue evaluate()
            throws SaxonApiException
Perform the query, returning the results as an XdmValue
Returns:
an XdmValue representing the results of the query
Throws:
SaxonApiException - if the query fails with a dynamic error

getContextItem

public XdmItem getContextItem()
Get the initial context item for the query, if one has been set
Returns:
the initial context item, or null if none has been set. This will not necessarily be the same object as was supplied, but it will be an XdmItem object that represents the same underlying node or atomic value.

getErrorListener

public ErrorListener getErrorListener()
Get the error listener.
Returns:
the ErrorListener in use

getExternalVariable

public XdmValue getExternalVariable(QName name)
Get the value that has been set for an external variable
Parameters:
name - the name of the external variable whose value is required
Returns:
the value that has been set for the external variable, or null if no value has been set

getTraceListener

public TraceListener getTraceListener()
Get the registered TraceListener, if any
Returns:
listener the TraceListener in use, or null if none has been set

getURIResolver

public URIResolver getURIResolver()
Get the URI resolver.
Returns:
the user-supplied URI resolver if there is one, or the system-defined one otherwise

getUnderlyingQueryContext

public DynamicQueryContext getUnderlyingQueryContext()
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

iterator

public Iterator iterator()
            throws SaxonApiUncheckedException
Get an iterator over the results of the query
Throws:
SaxonApiUncheckedException - if a dynamic error is detected while constructing the iterator. It is also possible for an SaxonApiUncheckedException to be thrown by the hasNext() method of the returned iterator if a dynamic error occurs while evaluating the result sequence.

run

public void run()
            throws SaxonApiException
Perform the query, sending the results to a previously specified destination
Throws:
SaxonApiException - if any dynamic error occurs during the query

run

public void run(Destination destination)
            throws SaxonApiException
Perform the query, sending the results to a specified destination
Parameters:
destination - The destination where the result document will be sent
Throws:
SaxonApiException - if any dynamic error occurs during the query

setContextItem

public void setContextItem(XdmItem item)
Set the initial context item for the query
Parameters:
item - the initial context item, or null if there is to be no initial context item

setDestination

public void setDestination(Destination destination)
Set the destination of the query
Parameters:
destination - the destination to which the results of the query will be sent

setErrorListener

public void setErrorListener(ErrorListener listener)
Set the error listener. The error listener receives reports of all run-time errors and can decide how to report them.
Parameters:
listener - the ErrorListener to be used

setExternalVariable

public void setExternalVariable(QName name,
                                XdmValue value)
Set the value of external variable defined in the query
Parameters:
name - the name of the external variable, as a QName
value - the value of the external variable, or null to clear a previously set value

setSource

public void setSource(Source source)
            throws SaxonApiException
Set the source document for the query. This method is equivalent to building a document from the supplied source object, and then supplying the document node of the resulting document as the initial context node.
Parameters:
source - the principal source document for the transformation

setTraceListener

public void setTraceListener(TraceListener listener)
Set a TraceListener which will receive messages relating to the evaluation of all expressions. This option has no effect unless the query was compiled to enable tracing.
Parameters:
listener - the TraceListener to use

setURIResolver

public void setURIResolver(URIResolver resolver)
Set an object that will be used to resolve URIs used in fn:document() and related functions.
Parameters:
resolver - An object that implements the URIResolver interface, or null.