public class XQueryEvaluator extends java.lang.Object implements java.lang.Iterable<XdmItem>, Destination
XQueryEvaluator
represents a compiled and loaded query ready for execution.
The XQueryEvaluator
holds details of the dynamic evaluation context for the query.
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
query several times. Running the query 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.
An XQueryEvaluator
is itself a Destination
. This means it is possible to use
one XQueryEvaluator
as the destination to receive the results of another transformation,
this providing a simple way for transformations to be chained into a pipeline. When the query is executed
this way, setDestination(Destination)
must be called to provide a destination for the result of this query.
Note however that a when the input to a query is supplied in this way, it will always be built as a tree in
memory, rather than the transformation being streamed.
Modifier | Constructor and Description |
---|---|
protected |
XQueryEvaluator(Processor processor,
XQueryExpression expression)
Protected constructor
|
Modifier and Type | Method and Description |
---|---|
XdmValue |
callFunction(QName function,
XdmValue[] arguments)
Call a global user-defined function in the compiled query.
|
void |
close()
Close this destination, allowing resources to be released.
|
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
|
javax.xml.transform.ErrorListener |
getErrorListener()
Get the error listener.
|
XdmValue |
getExternalVariable(QName name)
Get the value that has been set for an external variable
|
Receiver |
getReceiver(Configuration config)
Return a Receiver which can be used to supply the principal source document for the transformation.
|
ValidationMode |
getSchemaValidationMode()
Get the schema validation mode for the transformation.
|
Logger |
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.
|
java.util.Iterator<XdmNode> |
getUpdatedDocuments()
After executing an updating query using the
run() method, iterate over the root
nodes of the documents updated by the query. |
javax.xml.transform.URIResolver |
getURIResolver()
Get the URI resolver.
|
XdmSequenceIterator |
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 |
runStreamed(javax.xml.transform.Source source,
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(javax.xml.transform.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(javax.xml.transform.Source source)
Set the source document for the query.
|
void |
setTraceFunctionDestination(Logger 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(javax.xml.transform.URIResolver resolver)
Set an object that will be used to resolve URIs used in
fn:doc() and related functions.
|
protected XQueryEvaluator(Processor processor, XQueryExpression expression)
processor
- the Saxon processorexpression
- the XQuery expressionpublic void setSchemaValidationMode(ValidationMode mode)
doc()
, document()
,
or collection()
functions.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.public ValidationMode getSchemaValidationMode()
doc()
, document()
,
or collection()
functions.public void setSource(javax.xml.transform.Source source) throws SaxonApiException
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 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
DocumentBuilder.build(javax.xml.transform.Source)
, and the document
node of this tree is then used as the context item for the query.
source
- the source document to act as the initial context item for the query.SaxonApiException
public void setContextItem(XdmItem item) throws SaxonApiUncheckedException
item
- the initial context item, or null if there is to be no initial context itemSaxonApiUncheckedException
- if the query declares the context item and does not define
it to be externalpublic XdmItem getContextItem()
public void setExternalVariable(QName name, XdmValue value)
name
- the name of the external variable, as a QNamevalue
- the value of the external variable, or null to clear a previously set valuepublic XdmValue getExternalVariable(QName name)
name
- the name of the external variable whose value is requiredpublic void setURIResolver(javax.xml.transform.URIResolver resolver)
resolver
- An object that implements the URIResolver interface, or
null.public javax.xml.transform.URIResolver getURIResolver()
public void setErrorListener(javax.xml.transform.ErrorListener listener)
listener
- the ErrorListener to be usedpublic javax.xml.transform.ErrorListener getErrorListener()
public void setTraceListener(TraceListener listener)
listener
- the TraceListener to usepublic TraceListener getTraceListener()
public void setTraceFunctionDestination(Logger stream)
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.public Logger getTraceFunctionDestination()
public void setDestination(Destination destination)
destination
- the destination to which the results of the query will be sentpublic void run() throws SaxonApiException
getUpdatedDocuments()
method.SaxonApiException
- if any dynamic error occurs during the queryjava.lang.IllegalStateException
- if this is a non-updating query and no Destination has been
supplied for the query resultspublic void run(Destination destination) throws SaxonApiException
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.
destination
- The destination where the result document will be sentSaxonApiException
- if any dynamic error occurs during the queryjava.lang.IllegalStateException
- if this is an updating querypublic void runStreamed(javax.xml.transform.Source source, Destination destination) throws SaxonApiException
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.
source
- the input stream whose document node will act as the initial context item.
Should be a SAXSource or StreamSourcedestination
- The destination where the result document will be sentSaxonApiException
- if any dynamic error occurs during the queryjava.lang.IllegalStateException
- if this is an updating querypublic XdmValue evaluate() throws SaxonApiException
SaxonApiException
- if the query fails with a dynamic errorjava.lang.IllegalStateException
- if this is an updating querypublic XdmItem evaluateSingle() throws SaxonApiException
XdmItem
(that is,
a single node or atomic value).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.SaxonApiException
- if a dynamic error occurs during the query evaluation.public XdmSequenceIterator iterator() throws SaxonApiUncheckedException
This method must not be used with an updating query.
iterator
in interface java.lang.Iterable<XdmItem>
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.java.lang.IllegalStateException
- if this is an updating querypublic Receiver getReceiver(Configuration config) throws SaxonApiException
Saxon calls this method to obtain a Receiver, to which it then sends
a sequence of events representing the content of an XML document. This method is provided so that
XQueryEvaluator
implements Destination
, allowing one transformation
to receive the results of another in a pipeline.
Note that when an XQueryEvaluator
is used as a Destination
, the initial
context node set on that XQueryEvaluator
(using setSource(javax.xml.transform.Source)
) is ignored.
getReceiver
in interface Destination
config
- The Saxon configuration. This is supplied so that the destination can
use information from the configuration (for example, a reference to the name pool)
to construct or configure the returned Receiver.SaxonApiException
- if the Receiver cannot be createdjava.lang.IllegalStateException
- if no Destination has been suppliedpublic void close() throws SaxonApiException
XQueryEvaluator
is acting
as the destination of another transformation or query. Saxon calls this method when it has finished writing
to the destination.close
in interface Destination
SaxonApiException
- if any failure occurspublic java.util.Iterator<XdmNode> getUpdatedDocuments()
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.
public XdmValue callFunction(QName function, XdmValue[] arguments) throws SaxonApiException
function
- The name of the function to be calledarguments
- The values of the arguments to be supplied to the function. If necessary
these are converted to the required type by applying the function conversion rules.SaxonApiException
- if no function has been defined with the given name and arity;
or if any of the arguments does not match its required type according to the function
signature; or if a dynamic error occurs in evaluating the function.public DynamicQueryContext getUnderlyingQueryContext()
Copyright (c) 2004-2018 Saxonica Limited. All rights reserved.