net.sf.saxon.s9api
public class XQueryEvaluator extends Object implements Iterable<XdmItem>
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 | |
---|---|
XdmValue | evaluate()
Perform the query, returning the results as an XdmValue. |
XdmItem | evaluateSingle()
Evaluate the XQuery expression, returning the result as an XdmItem (that is,
a single node or atomic value).
|
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 |
ValidationMode | getSchemaValidationMode()
Get the schema validation mode for the transformation. |
PrintStream | getTraceFunctionDestination()
Get the destination for output from the fn:trace() function. |
TraceListener | getTraceListener()
Get the registered TraceListener, if any |
DynamicQueryContext | getUnderlyingQueryContext()
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.
|
URIResolver | getURIResolver()
Get the URI resolver.
|
Iterator<XdmItem> | iterator()
Evaluate the query, and return an iterator over its results.
|
void | run()
Perform the query.
|
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 to be used for the query results |
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 | setSchemaValidationMode(ValidationMode mode)
Set the schema validation mode for the transformation. |
void | setSource(Source source)
Set the source document for the query.
|
void | setTraceFunctionDestination(PrintStream stream)
Set the destination for output from the fn:trace() function.
|
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:doc() and related functions.
|
Parameters: processor the Saxon processor expression the XQuery expression
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
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
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.
Returns: the ErrorListener in use
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
doc()
, document()
,
or collection()
functions.Returns: the validation mode.
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
Returns: listener the TraceListener in use, or null if none has been set
Returns: the underlying object representing the dynamic context for query execution
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
Returns: the user-supplied URI resolver if there is one, or the system-defined one otherwise
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
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
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
Parameters: item the initial context item, or null if there is to be no initial context item
Parameters: destination the destination to which the results of the query will be sent
Parameters: listener the ErrorListener to be used
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
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.
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.
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
Parameters: listener the TraceListener to use
Parameters: resolver An object that implements the URIResolver interface, or null.