Saxon.Api

 

 

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

Destination for reporting warnings and non-fatal errors (including validation errors that occur when validating constructed nodes, which will eventually cause the transformation to fail)

 Processor Processor

Get the Processor from which this XQueryCompiler was constructed

 SchemaValidationMode SchemaValidationMode

The SchemaValidationMode to be used in this query, especially for documents loaded using the doc(), document(), or collection() functions.

 ResourceResolver 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.

 TextWriter TraceFunctionDestination

Destination for output of messages produced using the trace() function.

 ResourceResolver 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.

 

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 XdmValue (that is, a sequence of nodes and/or atomic values).

 XdmItem EvaluateSingle ()

Evaluate the query, returning the result as an XdmItem (that is, a single node or atomic value).

 IEnumerator GetEnumerator ()

Evaluate the query, returning the result as an IEnumerator (that is, an enumerator over a sequence of nodes and/or atomic values).

 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

public XdmItem ContextItem {get; set; }

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

public ErrorReporter ErrorReporter {set; }

Destination for reporting warnings and non-fatal errors (including validation errors that occur when validating constructed nodes, which will eventually cause the transformation to fail)

Processor

public Processor Processor {get; }

Get the Processor from which this XQueryCompiler was constructed

SchemaValidationMode

public SchemaValidationMode SchemaValidationMode {get; set; }

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

public ResourceResolver TextResolver {get; set; }

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

public TextWriter TraceFunctionDestination {get; set; }

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

public ResourceResolver XmlDocumentResolver {get; set; }

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 a NodeResource or an XmlReaderResource whose getItem() method delivers an XdmNode;
  • A TextResource delivering lexical XML in its Content 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

public XdmValue CallFunction(QName function,
XdmValue[] arguments)
throws
ArgumentException,
SaxonApiException

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 called
arguments -  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:

ArgumentException - 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.
SaxonApiException - If a dynamic error occurs in evaluating the function.

Evaluate

public XdmValue Evaluate()
throws
SaxonApiException

Evaluate the query, returning the result as an XdmValue (that is, a sequence of nodes and/or atomic values).

Returns:

An XdmValue representing the results of the query

Throws:

SaxonApiException - Throws a SaxonApiException if any run-time failure occurs while evaluating the query.

EvaluateSingle

public XdmItem EvaluateSingle()
throws
SaxonApiException

Evaluate the query, 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 query returns a sequence of more than one item, any items after the first are ignored.

Throws:

SaxonApiException - Throws a DynamicError if any run-time failure occurs while evaluating the expression.

GetEnumerator

public IEnumerator 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:

An enumerator over the sequence that represents the results of the query. Each object in this sequence will be an instance of 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 - Throws a SaxonApiException if any run-time failure occurs while evaluating the expression.

Run

public void Run(IDestination destination)
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:

SaxonApiException - Throws a DynamicError if any run-time failure occurs while evaluating the expression.

RunStreamed

public void RunStreamed(Stream input,
Uri baseUri,
IDestination destination)
throws
SaxonApiException

Execute a streamed query.

Parameters:

input - The input stream, which must contain a well-formed XML document
baseUri - The base URI of the document supplied on the input stream
destination - The destination to which the query result will be sent

Throws:

SaxonApiException - Throws a SaxonApiException if any run-time failure occurs while evaluating the query, or if the query execution cannot be streamed.

RunUpdate

public XdmNode[] RunUpdate()
throws
SaxonApiException

Execute an updating query.

Returns:

An array containing the root nodes of documents that have been updated by the query.

Throws:

SaxonApiException - Throws a SaxonApiException if any run-time failure occurs while evaluating the expression, or if the expression is not an updating query.

SetExternalVariable

public void SetExternalVariable(QName name,
XdmValue value)

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.