net.sf.saxon.s9api

Class XQueryEvaluator

public class XQueryEvaluator extends Object implements Iterable<XdmItem>

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
protected XQueryEvaluator(Processor processor, XQueryExpression expression)
Protected constructor
Method Summary
XdmValueevaluate()
Perform the query, returning the results as an XdmValue.
XdmItemevaluateSingle()
Evaluate the XQuery expression, returning the result as an XdmItem (that is, a single node or atomic value).
XdmItemgetContextItem()
Get the initial context item for the query, if one has been set
ErrorListenergetErrorListener()
Get the error listener.
XdmValuegetExternalVariable(QName name)
Get the value that has been set for an external variable
ValidationModegetSchemaValidationMode()
Get the schema validation mode for the transformation.
PrintStreamgetTraceFunctionDestination()
Get the destination for output from the fn:trace() function.
TraceListenergetTraceListener()
Get the registered TraceListener, if any
DynamicQueryContextgetUnderlyingQueryContext()
Get the underlying dynamic context object.
Iterator<XdmNode>getUpdatedDocuments()
After executing an updating query using the run method, iterate over the root nodes of the documents updated by the query.
URIResolvergetURIResolver()
Get the URI resolver.
Iterator<XdmItem>iterator()
Evaluate the query, and return an iterator over its results.
voidrun()
Perform the query.
voidrun(Destination destination)
Perform the query, sending the results to a specified destination.
voidsetContextItem(XdmItem item)
Set the initial context item for the query
voidsetDestination(Destination destination)
Set the destination to be used for the query results
voidsetErrorListener(ErrorListener listener)
Set the error listener.
voidsetExternalVariable(QName name, XdmValue value)
Set the value of external variable defined in the query
voidsetSchemaValidationMode(ValidationMode mode)
Set the schema validation mode for the transformation.
voidsetSource(Source source)
Set the source document for the query.
voidsetTraceFunctionDestination(PrintStream stream)
Set the destination for output from the fn:trace() function.
voidsetTraceListener(TraceListener listener)
Set a TraceListener which will receive messages relating to the evaluation of all expressions.
voidsetURIResolver(URIResolver resolver)
Set an object that will be used to resolve URIs used in fn:doc() and related functions.

Constructor Detail

XQueryEvaluator

protected XQueryEvaluator(Processor processor, XQueryExpression expression)
Protected constructor

Parameters: processor the Saxon processor expression the XQuery expression

Method Detail

evaluate

public XdmValue evaluate()
Perform the query, returning the results as an XdmValue. This method must not be used with an updating query

Returns: an XdmValue representing the results of the query

Throws: SaxonApiException if the query fails with a dynamic error IllegalStateException if this is an updating query

evaluateSingle

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

Returns: an XdmItem representing the result of the query, or null if the query 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 query evaluation.

Since: 9.2

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

getSchemaValidationMode

public ValidationMode getSchemaValidationMode()
Get the schema validation mode for the transformation. This indicates how source documents loaded specifically for this transformation will be handled. This applies to the principal source document if supplied as a SAXSource or StreamSource, and to all documents loaded during the transformation using the doc(), document(), or collection() functions.

Returns: the validation mode.

getTraceFunctionDestination

public PrintStream getTraceFunctionDestination()
Get the destination for output from the fn:trace() function.

Returns: the PrintStream to which trace output will be sent. If no explicitly destination has been set, returns System.err. If the destination has been set to null to suppress trace output, returns null.

Since: 9.1

getTraceListener

public TraceListener getTraceListener()
Get the registered TraceListener, if any

Returns: listener the TraceListener in use, or null if none has been set

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

getUpdatedDocuments

public Iterator<XdmNode> getUpdatedDocuments()
After executing an updating query using the run method, iterate over the root nodes of the documents updated by the query.

The results remain available until a new query is executed. This method returns the results of the most recently executed query. It does not consume the results.

Returns: an iterator over the root nodes of documents (or other trees) that were updated by the query

Since: 9.1

getURIResolver

public URIResolver getURIResolver()
Get the URI resolver.

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

iterator

public Iterator<XdmItem> iterator()
Evaluate the query, and return an iterator over its results.

This method must not be used with an updating 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. IllegalStateException if this is an updating query

run

public void run()
Perform the query.

Throws: net.sf.saxon.s9api.SaxonApiException if any dynamic error occurs during the query IllegalStateException if this is a non-updating query and no Destination has been supplied for the query results

run

public void run(Destination destination)
Perform the query, sending the results to a specified destination.

This method must not be used with an updating query.

This method is designed for use with a query that produces a single node (typically a document node or element node) as its result. If the query produces multiple nodes, the effect depends on the kind of destination. For example, if the result is an XdmDestination, only the last of the nodes will be accessible.

Parameters: destination The destination where the result document will be sent

Throws: net.sf.saxon.s9api.SaxonApiException if any dynamic error occurs during the query IllegalStateException if this is an updating 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 to be used for the query results

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

setSchemaValidationMode

public void setSchemaValidationMode(ValidationMode mode)
Set the schema validation mode for the transformation. This indicates how source documents loaded specifically for this transformation will be handled. This applies to the principal source document if supplied as a SAXSource or StreamSource, and to all documents loaded during the transformation using the doc(), document(), or collection() functions.

Parameters: mode the validation mode. Passing null causes no change to the existing value. Passing Validation.DEFAULT resets to the initial value, which determines the validation requirements from the Saxon Configuration.

setSource

public void setSource(Source source)
Set the source document for the query.

If the source is an instance of NodeInfo, the supplied node is used directly as the context node of the query.

If the source is an instance of javax.xml.transform.dom.DOMSource, the DOM node identified by the DOMSource is wrapped as a Saxon node, and this is then used as the context item

In all other cases a new Saxon tree is built, by calling build, and the document node of this tree is then used as the context item for the query.

Parameters: source the source document to act as the initial context item for the query.

setTraceFunctionDestination

public void setTraceFunctionDestination(PrintStream stream)
Set the destination for output from the fn:trace() function. By default, the destination is System.err. If a TraceListener is in use, this is ignored, and the trace() output is sent to the TraceListener.

Parameters: stream the PrintStream to which trace output will be sent. If set to null, trace output is suppressed entirely. It is the caller's responsibility to close the stream after use.

Since: 9.1

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:doc() and related functions.

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