Package net.sf.saxon.s9api

## Class XQueryEvaluator

- java.lang.Object
- - net.sf.saxon.s9api.AbstractDestination
  - - net.sf.saxon.s9api.XQueryEvaluator

- All Implemented Interfaces:
    `java.lang.Iterable<XdmItem>`, `Destination`

      public class XQueryEvaluator
      extends AbstractDestination
      implements java.lang.Iterable<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`.

  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.

  As a `Destination`, an `XQueryEvaluator` performs sequence normalization as defined in the Serialization specification, including inserting item separators if required. The input to the query (the global context item) will therefore always be a single document node. This will always be built as a tree in memory, it will never be streamed.

- - ### Field Summary

    - ### Fields inherited from class net.sf.saxon.s9api.AbstractDestination

      `helper`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `XQueryEvaluator​(Processor processor, XQueryExpression expression)` | Protected constructor

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | 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.
    `ErrorReporter` | `getErrorReporter()` | Get the recipient of error information previously registered using `setErrorReporter(ErrorReporter)`.
    `XdmValue` | `getExternalVariable​(QName name)` | Get the value that has been set for an external variable
    `Receiver` | `getReceiver​(PipelineConfiguration pipe, SerializationProperties params)` | 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<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` | `runStreamed​(javax.xml.transform.Source source, Destination destination)` | Perform the query in streaming mode, 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` | `setErrorReporter​(ErrorReporter reporter)` | Supply a callback which will be notified of all dynamic errors and warnings encountered during this query evaluation.
    `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.
    `XdmStream<XdmItem>` | `stream()` | Evaluate the query, returning the result as an `Stream`.

    - ### Methods inherited from class net.sf.saxon.s9api.AbstractDestination

      `closeAndNotify, getDestinationBaseURI, onClose, setDestinationBaseURI`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface java.lang.Iterable

      `forEach, spliterator`

- - ### Constructor Detail

    - #### XQueryEvaluator

          protected XQueryEvaluator​(Processor processor,
                                    XQueryExpression expression)

      Protected constructor
      Parameters:
        `processor` - the Saxon processor
        `expression` - the XQuery expression

  - ### Method Detail

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

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

    - #### setSource

          public void setSource​(javax.xml.transform.Source source)
                         throws SaxonApiException

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

      Parameters:
        `source` - the source document to act as the initial context item for the query.
      Throws:
        `SaxonApiException`

    - #### setContextItem

          public void setContextItem​(XdmItem item)
                              throws SaxonApiException

      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
      Throws:
        `SaxonApiException` - if the query declares the context item and does not define it to be external

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

    - #### 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
      Throws:
        `SaxonApiUncheckedException` - if the value is evaluated lazily, and evaluation fails

    - #### 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

    - #### setURIResolver

          public void setURIResolver​(javax.xml.transform.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.

    - #### getURIResolver

          public javax.xml.transform.URIResolver getURIResolver()

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

    - #### setErrorListener

          public void setErrorListener​(javax.xml.transform.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

    - #### getErrorListener

          public javax.xml.transform.ErrorListener getErrorListener()

      Get the error listener.
      Returns:
        the ErrorListener in use

    - #### setErrorReporter

          public void setErrorReporter​(ErrorReporter reporter)

      Supply a callback which will be notified of all dynamic errors and warnings encountered during this query evaluation.

      Calling this method overwrites the effect of any previous call on `setErrorListener(ErrorListener)` or `setErrorList`.

      If no error reporter is supplied by the caller, error information will be written to the standard error stream.

      Parameters:
        `reporter` - a callback function which will be notified of all Static errors and warnings encountered during a compilation episode.
      Since:
        11.2 and retrofitted to 10.7

    - #### getErrorReporter

          public ErrorReporter getErrorReporter()

      Get the recipient of error information previously registered using `setErrorReporter(ErrorReporter)`.
      Returns:
        the recipient previously registered explicitly using `setErrorReporter(ErrorReporter)`, or implicitly using `setErrorListener(ErrorListener)`. If no error reporter has been registered, the result may be null, or may return a system supplied error reporter.
      Since:
        11.2 and retrofitted to 10.7

    - #### 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

    - #### getTraceListener

          public TraceListener getTraceListener()

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

    - #### setTraceFunctionDestination

          public void setTraceFunctionDestination​(Logger 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. Changed in 9.6 to use a Logger

    - #### getTraceFunctionDestination

          public Logger 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. Changed in 9.6 to use a Logger

    - #### 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

    - #### run

          public void run()
                   throws SaxonApiException

      Perform the query.
      - In the case of a non-updating query, the results are sent to the registered Destination.
      - In the case of an updating query, all updated documents will be available after query execution as the result of the `getUpdatedDocuments()` method.
      Throws:
        `SaxonApiException` - if any dynamic error occurs during the query
        `java.lang.IllegalStateException` - if this is a non-updating query and no Destination has been supplied for the query results

    - #### run

          public void run​(Destination destination)
                   throws SaxonApiException

      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:
        `SaxonApiException` - if any dynamic error occurs during the query
        `java.lang.IllegalStateException` - if this is an updating query

    - #### runStreamed

          public void runStreamed​(javax.xml.transform.Source source,
                                  Destination destination)
                           throws SaxonApiException

      Perform the query in streaming mode, 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:
        `source` - the input stream whose document node will act as the initial context item. Should be a SAXSource or StreamSource
        `destination` - The destination where the result document will be sent
      Throws:
        `SaxonApiException` - if any dynamic error occurs during the query
        `java.lang.IllegalStateException` - if this is an updating query

    - #### evaluate

          public XdmValue evaluate()
                            throws SaxonApiException

      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
        `java.lang.IllegalStateException` - if this is an updating query

    - #### evaluateSingle

          public XdmItem evaluateSingle()
                                 throws SaxonApiException

      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

    - #### iterator

          public XdmSequenceIterator<XdmItem> iterator()
                                                throws SaxonApiUncheckedException

      Evaluate the query, and return an iterator over its results.

      This method must not be used with an updating query.

      Specified by:
        `iterator` in interface `java.lang.Iterable<XdmItem>`
      Returns:
        an Iterator<XdmItem>. The XdmSequenceIterator class is a standard Java Iterator with an additional close() method, which should be called to release resources if the client does not intend to read any more items from the iterator.
      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.
        `java.lang.IllegalStateException` - if this is an updating query
      Since:
        9.5.1.5. Previously the method returned Iterator<XdmItem>; the signature changed in Saxon 9.5.1.5 for reasons described in bug 2016.

    - #### stream

          public XdmStream<XdmItem> stream()
                                    throws SaxonApiUncheckedException

      Evaluate the query, returning the result as an `Stream`.
      Returns:
        A stream delivering the results of the query. Each object in this stream will be an instance of `XdmItem`. Note that the expression may be evaluated lazily, which means that a successful response from this method does not imply that the expression has executed successfully: failures may be reported later while retrieving items from the iterator.
      Throws:
        `SaxonApiUncheckedException` - if a dynamic error occurs during XPath evaluation that can be detected at this point.

    - #### getReceiver

          public Receiver getReceiver​(PipelineConfiguration pipe,
                                      SerializationProperties params)
                               throws SaxonApiException

      Return a Receiver which can be used to supply the principal source document for the transformation. This method is intended primarily for internal use, though it can also be called by a user application that wishes to feed events into the query engine.

      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.

      Specified by:
        `getReceiver` in interface `Destination`
      Parameters:
        `pipe` - 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.
        `params` - the output serialization properties
      Returns:
        the Receiver to which events are to be sent.
      Throws:
        `SaxonApiException` - if the Receiver cannot be created
        `java.lang.IllegalStateException` - if no Destination has been supplied

    - #### close

          public void close()
                     throws SaxonApiException

      Close this destination, allowing resources to be released. Used when this `XQueryEvaluator` is acting as the destination of another transformation or query. Saxon calls this method when it has finished writing to the destination.
      Specified by:
        `close` in interface `Destination`
      Throws:
        `SaxonApiException` - if any failure occurs

    - #### getUpdatedDocuments

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

      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

    - #### callFunction

          public XdmValue callFunction​(QName function,
                                       XdmValue[] arguments)
                                throws 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. If necessary these are converted to the required type by applying the function conversion rules.
      Returns:
        the result of the function call as an XdmValue.
      Throws:
        `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.
      Since:
        9.3. Changed in 9.6 to apply the function conversion rules to the supplied arguments.

    - #### 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