Saxon.Api
Class XQueryEvaluator
-
public class XQueryEvaluator
- implements IEnumerable<XdmItem>
An 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
.
Property Summary |
|
---|---|
XdmItem | ContextItem The context item for the query. |
ErrorReporter | ErrorReporter
The |
Processor | Processor
Get the |
SchemaValidationMode | SchemaValidationMode
The |
ResourceResolver | TextResolver
The |
TextWriter | TraceFunctionDestination
Destination for output of messages produced using the |
ResourceResolver | XmlDocumentResolver
The |
Method Summary |
|
---|---|
XdmValue | CallFunction (QName function, XdmValue[] arguments) Call a global user-defined function in the compiled query. |
XdmValue | Evaluate ()
Evaluate the query, returning the result as an |
XdmItem | EvaluateSingle ()
Evaluate the query, returning the result as an |
IEnumerator | GetEnumerator ()
Evaluate the query, returning the result as an |
void | Run (IDestination destination) Evaluate the query, sending the result to a specified destination. |
void | RunStreamed (Stream input, Uri baseUri, IDestination destination) Execute a streamed query. |
XdmNode[] | RunUpdate () Execute an updating query. |
void | SetExternalVariable (QName name, XdmValue value) Set the value of an external variable declared in the query. |
Property Detail
ContextItem
The context item for the query.
This may be a node, an atomic value, or a function item such as a map or array.
Most commonly it will be a document node, which might be constructed
using a DocumentBuilder
created from the Processor
object.
ErrorReporter
The ErrorReporter
to be used at run-time to notify any dynamic
errors that occur.
Processor
Get the Processor
from which this XQueryCompiler
was constructed
SchemaValidationMode
The SchemaValidationMode
to be used in this query, especially for documents
loaded using the doc()
, document()
, or collection()
functions.
This does not affect any document supplied as the context item for the query, or as the values of external variables.
TextResolver
The TextResolver
to be used at run-time to resolve and dereference URIs
supplied to the unparsed-text()
, unparsed-text-lines()
,
unparsed-text-available()
, and json-doc()
functions.
TraceFunctionDestination
Destination for output of messages produced using the trace()
function.
If no specific destination is supplied by the caller, message information will be written to the standard error stream.
The supplied destination is ignored if a TraceListener
is in use.
The TextWriter
should be closed by the caller after use.
XmlDocumentResolver
The ResourceResolver
to be used at run-time to resolve and dereference URIs
supplied to the fn:doc()
and fn:doc-available()
functions, and other functions
that fetch XML resources such as fn:transform
.
The URI supplied as the first argument to the resolver is the absolute URI requested, that is, the result of resolving the requested relative URI against the relevant base URI.
The requested relative URI and the corresponding base URI are supplied as separate
properties within the ResourceProperties
argument, in case they are needed.
The returned IResource
must be one of the following:
- An
IResource
such as aNodeResource
or anXmlReaderResource
whosegetItem()
method delivers anXdmNode
; - A
TextResource
delivering lexical XML in itsContent
property; this will then be parsed to deliver the corresponding XML document.
If no XmlDocumentResolver
is supplied, or if it returns null, then
the CommonResourceResolver
associated with the Saxon Configuration is invoked.
Method Detail
CallFunction
XdmValue[] arguments)
throws
ArgumentException,
SaxonApiException
Evaluate
throws
SaxonApiException
Evaluate the query, returning the result as an XdmValue
(that is,
a sequence of nodes and/or atomic values).
Returns:
XdmValue
representing the results of the query
Throws:
SaxonApiException
if any run-time failure
occurs while evaluating the query.EvaluateSingle
throws
SaxonApiException
Evaluate the query, returning the result as an XdmItem
(that is,
a single node or atomic value).
Returns:
XdmItem
representing the result of the query, or null if the query
returns an empty sequence. If the query returns a sequence of more than one item,
any items after the first are ignored.
Throws:
DynamicError
if any run-time failure
occurs while evaluating the expression.GetEnumerator
throws
SaxonApiException
Evaluate the query, returning the result as an IEnumerator
(that is,
an enumerator over a sequence of nodes and/or atomic values).
Returns:
XdmItem
. Note
that the query may be evaluated lazily, which means that a successful response
from this method does not imply that the query has executed successfully: failures
may be reported later while retrieving items from the iterator.
Throws:
SaxonApiException
if any run-time failure
occurs while evaluating the expression.Run
throws
SaxonApiException
Evaluate the query, sending the result to a specified destination.
Parameters:
destination
-
The destination for the results of the query. The class XmlDestination
is an abstraction that allows a number of different kinds of destination
to be specified.
Throws:
DynamicError
if any run-time failure
occurs while evaluating the expression.RunStreamed
Uri baseUri,
IDestination destination)
throws
SaxonApiException
Execute a streamed query.
Parameters:
input
- The input stream, which must contain a well-formed XML documentbaseUri
- The base URI of the document supplied on the input streamdestination
- The destination to which the query result will be sentThrows:
SaxonApiException
if any run-time failure
occurs while evaluating the query, or if the query execution cannot be streamed.RunUpdate
throws
SaxonApiException
Execute an updating query.
Returns:
Throws:
SaxonApiException
if any run-time failure
occurs while evaluating the expression, or if the expression is not an
updating query.SetExternalVariable
Set the value of an external variable declared in the query.
Parameters:
name
- The name of the external variable, expressed
as a QName
. If an external variable of this name has been declared in the
query prolog, the given value will be assigned to the variable. If the
variable has not been declared, calling this method has no effect (it is
not an error).value
- The value to be given to the external variable.
If the variable declaration defines a required type for the variable, then
this value must match the required type: no conversions are applied.
Call a global user-defined function in the compiled query.
If this is called more than once (to evaluate the same function repeatedly with different arguments, or to evaluate different functions) then the sequence of evaluations uses the same values of global variables including external variables (query parameters); the effect of any changes made to query parameters between calls is undefined.
Parameters:
function
- The name of the function to be calledarguments
- The values of the arguments to be supplied to the function. These must be of the correct type as defined in the function signature (there is no automatic conversion to the required type).Throws: