Package net.sf.saxon.query

## Class XQueryExpression

- java.lang.Object
- - net.sf.saxon.query.XQueryExpression

- All Implemented Interfaces:
    `javax.xml.transform.SourceLocator`, `ExpressionOwner`, `Locatable`, `Location`, `Traceable`, `TraceableComponent`, `org.xml.sax.Locator`
  Direct Known Subclasses:
    `XQueryExpressionEE`

      public class XQueryExpression
      extends java.lang.Object
      implements Location, ExpressionOwner, TraceableComponent

  XQueryExpression represents a compiled query. This object is immutable and thread-safe, the same compiled query may be executed many times in series or in parallel. The object is intended to be created only by using the compileQuery method of the QueryProcessor class.

  Various methods are provided for evaluating the query, with different options for delivery of the results.

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected Executable` | `executable` |
    `protected Expression` | `expression` |
    `protected QueryModule` | `mainModule` |
    `protected SlotManager` | `stackFrameMap` |

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `XQueryExpression​(Expression exp, QueryModule mainModule, boolean streaming)` | The constructor should only be called using the compileQuery() methods of StaticQueryContext

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected void` | `closeStreamIfNecessary​(javax.xml.transform.stream.StreamResult result, boolean mustClose)` |
    `java.util.List<java.lang.Object>` | `evaluate​(DynamicQueryContext env)` | Execute a the compiled Query, returning the results as a List of objects obtained by converting the items in the query result to the nearest appropriate Java type
    `java.lang.Object` | `evaluateSingle​(DynamicQueryContext env)` | Execute the compiled Query, returning the first item in the result.
    `void` | `explain​(ExpressionPresenter out)` | Diagnostic method: display a representation of the compiled query on the selected output stream.
    `void` | `explainPathMap()` | Output the path map of the query for diagnostics
    `Expression` | `getBody()` | Get the expression at the root of the expression tree used to evaluate this construct
    `Expression` | `getChildExpression()` |
    `int` | `getColumnNumber()` | Return the character position where the current document event ends.
    `Configuration` | `getConfiguration()` | Get the Configuration to which this Container belongs
    `Executable` | `getExecutable()` | Get the Executable (representing a complete stylesheet or query) of which this Container forms part
    `Expression` | `getExpression()` | Get the expression wrapped in this XQueryExpression object
    `StructuredQName[]` | `getExternalVariableNames()` | Get a list containing the names of the external variables in the query.
    `HostLanguage` | `getHostLanguage()` | Get the host language (XSLT, XQuery, XPath) used to implement the code in this container
    `int` | `getLineNumber()` | Return the line number where the current document event ends.
    `Location` | `getLocation()` | Get the location of the construct
    `QueryModule` | `getMainModule()` | Get the static context in which this expression was compiled.
    `StructuredQName` | `getObjectName()` | Get a name identifying the object of the expression, for example a function name, template name, variable name, key name, element name, etc.
    `PackageData` | `getPackageData()` | Get data about the unit of compilation (XQuery module, XSLT package) to which this container belongs
    `java.lang.String` | `getPublicId()` | Return the public identifier for the current document event.
    `SlotManager` | `getStackFrameMap()` | Get the stack frame map used for the outermost level of this query
    `java.lang.String` | `getSystemId()` | Return the system identifier for the current document event.
    `java.lang.String` | `getTracingTag()` | Get a string to identify the type of component
    `protected XPathContextMajor` | `initialContext​(DynamicQueryContext dynamicEnv, Controller controller)` |
    `boolean` | `isDocumentProjectionAllowed()` | Ask whether document projection is allowed
    `boolean` | `isUpdateQuery()` | Ask whether this is an update query
    `SequenceIterator` | `iterator​(DynamicQueryContext env)` | Get an iterator over the results of the expression.
    `Controller` | `newController​(DynamicQueryContext env)` | Get a controller that can be used to execute functions in this compiled query.
    `void` | `run​(DynamicQueryContext env, javax.xml.transform.Result result, java.util.Properties outputProperties)` | Run the query, sending the results directly to a JAXP Result object.
    `void` | `runStreamed​(DynamicQueryContext dynamicEnv, javax.xml.transform.Source source, javax.xml.transform.Result result, java.util.Properties outputProperties)` | Run the query in streaming mode, assuming it has been compiled for streaming.
    `java.util.Set<MutableNodeInfo>` | `runUpdate​(DynamicQueryContext dynamicEnv)` | Run an updating query
    `void` | `runUpdate​(DynamicQueryContext dynamicEnv, UpdateAgent agent)` | Run an updating query, writing back eligible updated node to persistent storage.
    `Location` | `saveLocation()` | Get an immutable copy of this Location object.
    `void` | `setAllowDocumentProjection​(boolean allowed)` | Indicate that document projection is or is not allowed
    `void` | `setBody​(Expression expression)` | Set the expression to be used to evaluate this construct
    `void` | `setChildExpression​(Expression expr)` |
    `boolean` | `usesContextItem()` | Ask whether this query uses the context item
    `protected java.util.Properties` | `validateOutputProperties​(Controller controller, java.util.Properties outputProperties)` | Validate the serialization properties requested; any problems result in warnings being output

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

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

    - ### Methods inherited from interface net.sf.saxon.trace.Traceable

      `gatherProperties`

- - ### Field Detail

    - #### expression

          protected Expression expression

    - #### stackFrameMap

          protected SlotManager stackFrameMap

    - #### executable

          protected Executable executable

    - #### mainModule

          protected QueryModule mainModule

  - ### Constructor Detail

    - #### XQueryExpression

          public XQueryExpression​(Expression exp,
                                  QueryModule mainModule,
                                  boolean streaming)
                           throws XPathException

      The constructor should only be called using the compileQuery() methods of StaticQueryContext
      Parameters:
        `exp` - an expression to be wrapped as an XQueryExpression
        `mainModule` - the static context of the main module
        `streaming` - true if streamed execution is requested
      Throws:
        `XPathException` - if an error occurs

  - ### Method Detail

    - #### getExpression

          public Expression getExpression()

      Get the expression wrapped in this XQueryExpression object
      Returns:
        the underlying expression

    - #### getBody

          public Expression getBody()

      Description copied from interface: `TraceableComponent`
      Get the expression at the root of the expression tree used to evaluate this construct
      Specified by:
        `getBody` in interface `TraceableComponent`
      Returns:
        the root expression

    - #### getChildExpression

          public Expression getChildExpression()

      Specified by:
        `getChildExpression` in interface `ExpressionOwner`

    - #### setBody

          public void setBody​(Expression expression)

      Description copied from interface: `TraceableComponent`
      Set the expression to be used to evaluate this construct
      Specified by:
        `setBody` in interface `TraceableComponent`
      Parameters:
        `expression` - the evaluation expression

    - #### getObjectName

          public StructuredQName getObjectName()

      Get a name identifying the object of the expression, for example a function name, template name, variable name, key name, element name, etc. This is used only where the name is known statically.
      Specified by:
        `getObjectName` in interface `Traceable`
      Returns:
        the QName of the object declared or manipulated by this instruction or expression

    - #### getTracingTag

          public java.lang.String getTracingTag()

      Description copied from interface: `TraceableComponent`
      Get a string to identify the type of component
      Specified by:
        `getTracingTag` in interface `TraceableComponent`
      Returns:
        an identifying string

    - #### getLocation

          public Location getLocation()

      Description copied from interface: `Locatable`
      Get the location of the construct
      Specified by:
        `getLocation` in interface `Locatable`
      Returns:
        the location. If no location information is available, the method should return `Loc.NONE` rather than returning null. However, callers would be well advised to check for the result being null.

    - #### getPackageData

          public PackageData getPackageData()

      Get data about the unit of compilation (XQuery module, XSLT package) to which this container belongs

    - #### getConfiguration

          public Configuration getConfiguration()

      Get the Configuration to which this Container belongs
      Returns:
        the Configuration

    - #### usesContextItem

          public boolean usesContextItem()

      Ask whether this query uses the context item
      Returns:
        true if the context item is referenced either in the query body or in the initializer of any global variable

    - #### isUpdateQuery

          public boolean isUpdateQuery()

      Ask whether this is an update query
      Returns:
        true if the body of the query is an updating expression (as defined by the XQuery Update specification). Note that a query can use Update syntax (notably the copy-modify syntax) without being an updating expression.

    - #### getStackFrameMap

          public SlotManager getStackFrameMap()

      Get the stack frame map used for the outermost level of this query
      Returns:
        the stack frame map

    - #### explainPathMap

          public void explainPathMap()

      Output the path map of the query for diagnostics

    - #### getMainModule

          public QueryModule getMainModule()

      Get the static context in which this expression was compiled. This is essentially an internal copy of the original user-created StaticQueryContext object, augmented with information obtained from the query prolog of the main query module, and with information about functions and variables imported from other library modules. The user-created StaticQueryContext object is not modified by Saxon, whereas the QueryModule object includes additional information found in the query prolog.
      Returns:
        the QueryModule object representing the static context of the main module of the query. This is available for inspection, but must not be modified or reused by the application.

    - #### getExternalVariableNames

          public StructuredQName[] getExternalVariableNames()

      Get a list containing the names of the external variables in the query.

      Changed in Saxon 9.0 to return an array of StructuredQName objects rather than integer fingerprints.

      Returns:
        an array of StructuredQName objects, representing the names of external variables defined in the query

    - #### evaluate

          public java.util.List<java.lang.Object> evaluate​(DynamicQueryContext env)
                                                    throws XPathException

      Execute a the compiled Query, returning the results as a List of objects obtained by converting the items in the query result to the nearest appropriate Java type
      Parameters:
        `env` - Provides the dynamic query evaluation context
      Returns:
        The results of the expression, as a List. The List represents the sequence of items returned by the expression. Each item in the list will either be an object representing a node, or an object representing an atomic value. For the types of Java object that may be returned, see the description of the `XPathEvaluator.evaluate(java.lang.String, java.lang.Object, javax.xml.namespace.QName)` method of class XPathProcessor
      Throws:
        `XPathException` - if a dynamic error occurs during query evaluation

    - #### evaluateSingle

          public java.lang.Object evaluateSingle​(DynamicQueryContext env)
                                          throws XPathException

      Execute the compiled Query, returning the first item in the result. This is useful where it is known that the expression will only return a singleton value (for example, a single node, or a boolean).
      Parameters:
        `env` - Provides the dynamic query evaluation context
      Returns:
        The first item in the sequence returned by the expression. If the expression returns an empty sequence, this method returns null. Otherwise, it returns the first item in the result sequence, represented as a Java object using the same mapping as for the `evaluate(net.sf.saxon.query.DynamicQueryContext)` method
      Throws:
        `XPathException` - if evaluation fails with a dynamic error

    - #### iterator

          public SequenceIterator iterator​(DynamicQueryContext env)
                                    throws XPathException

      Get an iterator over the results of the expression. This returns results without any conversion of the returned items to "native" Java classes. The iterator will deliver a sequence of Item objects, each item being either a NodeInfo (representing a node) or an AtomicValue (representing an atomic value).

      To get the results of the query in the form of an XML document in which each item is wrapped by an element indicating its type, use:

      `QueryResult.wrap(iterator(env))`

      To serialize the results to a file, use the QueryResult.serialize() method.

      Parameters:
        `env` - Provides the dynamic query evaluation context
      Returns:
        an iterator over the results of the query. The class SequenceIterator is modeled on the standard Java Iterator class, but has extra functionality and can throw exceptions when errors occur.
      Throws:
        `XPathException` - if a dynamic error occurs in evaluating the query. Some dynamic errors will not be reported by this method, but will only be reported when the individual items of the result are accessed using the returned iterator.

    - #### run

          public void run​(DynamicQueryContext env,
                          javax.xml.transform.Result result,
                          java.util.Properties outputProperties)
                   throws XPathException

      Run the query, sending the results directly to a JAXP Result object. This way of executing the query is most efficient in the case of queries that produce a single document (or parentless element) as their output, because it avoids constructing the result tree in memory: instead, it is piped straight to the serializer.

      If the output method specified in the outputProperties, or declared in the query itself, is one of XML, HTML, XHTML, or TEXT, or if it is defaulted to XML, then the query is implicitly wrapped in a document node constructor to implement the "sequence normalization" phase described in the Serialization specification. If the output method is JSON or ADAPTIVE then this phase is skipped and the items produced by the query are piped straight into the serializer.

      Parameters:
        `env` - the dynamic query context
        `result` - the destination for the results of the query. The query is effectively wrapped in a document{} constructor, so that the items in the result are concatenated to form a single document; this is then written to the requested Result destination, which may be (for example) a DOMResult, a SAXResult, or a StreamResult
        `outputProperties` - Supplies serialization properties, in JAXP format, if the result is to be serialized. This parameter can be defaulted to null.
      Throws:
        `XPathException` - if the query fails.

    - #### closeStreamIfNecessary

          protected void closeStreamIfNecessary​(javax.xml.transform.stream.StreamResult result,
                                                boolean mustClose)
                                         throws XPathException

      Throws:
        `XPathException`

    - #### runStreamed

          public void runStreamed​(DynamicQueryContext dynamicEnv,
                                  javax.xml.transform.Source source,
                                  javax.xml.transform.Result result,
                                  java.util.Properties outputProperties)
                           throws XPathException

      Run the query in streaming mode, assuming it has been compiled for streaming. This requires Saxon-EE.
      Parameters:
        `dynamicEnv` - the dynamic execution context
        `source` - the input document, as a SAXSource or StreamSource
        `result` - the destination for the query results
        `outputProperties` - serialization options for the query result
      Throws:
        `XPathException` - if streamed evaluation of the query fails

    - #### validateOutputProperties

          protected java.util.Properties validateOutputProperties​(Controller controller,
                                                                  java.util.Properties outputProperties)

      Validate the serialization properties requested; any problems result in warnings being output
      Parameters:
        `controller` - The query controller
        `outputProperties` - the requested serialization properties (may be null)
      Returns:
        the properties after validation and normalization

    - #### runUpdate

          public java.util.Set<MutableNodeInfo> runUpdate​(DynamicQueryContext dynamicEnv)
                                                   throws XPathException

      Run an updating query
      Parameters:
        `dynamicEnv` - the dynamic context for query execution
      Returns:
        a set of nodes representing the roots of trees that have been modified as a result of executing the update. Note that this method will never modify persistent data on disk; it returns the root nodes of the affected documents (which will often be document nodes whose document-uri can be ascertained), and it is the caller's responsibility to decide what to do with them.

        On completion of this method it is generally unsafe to rely on the contents or relationships of NodeInfo objects that were obtained before the updating query was run. Such objects may or may not reflect the results of the update operations. This is especially true in the case of nodes that are part of a subtree that has been deleted (detached from its parent). Instead, the new updated tree should be accessed by navigation from the root nodes returned by this method.

      Throws:
        `XPathException` - if evaluation of the update query fails, or it this is not an updating query

    - #### runUpdate

          public void runUpdate​(DynamicQueryContext dynamicEnv,
                                UpdateAgent agent)
                         throws XPathException

      Run an updating query, writing back eligible updated node to persistent storage.

      A node is eligible to be written back to disk if it is present in the document pool, which generally means that it was originally read using the doc() or collection() function.

      On completion of this method it is generally unsafe to rely on the contents or relationships of NodeInfo objects that were obtained before the updating query was run. Such objects may or may not reflect the results of the update operations. This is especially true in the case of nodes that are part of a subtree that has been deleted (detached from its parent). Instead, the new updated tree should be accessed by navigation from the root nodes returned by this method.

      If one or more eligible updated nodes cannot be written back to disk, perhaps because the URI identifies a non-updatable location, then an exception is thrown. In this case it is undefined

      Parameters:
        `dynamicEnv` - the dynamic context for query execution
        `agent` - a callback class that is called to process each document updated by the query
      Throws:
        `XPathException` - if evaluation of the update query fails, or it this is not an updating query

    - #### initialContext

          protected XPathContextMajor initialContext​(DynamicQueryContext dynamicEnv,
                                                     Controller controller)
                                              throws XPathException

      Throws:
        `XPathException`

    - #### newController

          public Controller newController​(DynamicQueryContext env)
                                   throws XPathException

      Get a controller that can be used to execute functions in this compiled query. Functions in the query module can be found using `QueryModule.getUserDefinedFunction(java.lang.String, java.lang.String, int)`. They can then be called directly from the Java application using `UserFunction.call(net.sf.saxon.expr.XPathContext, net.sf.saxon.om.Sequence[])` The same Controller can be used for a series of function calls. Note that the Controller should only be used in a single thread.
      Parameters:
        `env` - the dynamic context for evaluation
      Returns:
        a newly constructed Controller
      Throws:
        `XPathException` - if evaluation fails with a dynamic error

    - #### explain

          public void explain​(ExpressionPresenter out)
                       throws XPathException

      Diagnostic method: display a representation of the compiled query on the selected output stream.
      Parameters:
        `out` - an ExpressionPresenter to which the XML representation of the compiled query will be sent
      Throws:
        `XPathException`

    - #### getExecutable

          public Executable getExecutable()

      Get the Executable (representing a complete stylesheet or query) of which this Container forms part
      Returns:
        the Executable

    - #### setAllowDocumentProjection

          public void setAllowDocumentProjection​(boolean allowed)

      Indicate that document projection is or is not allowed
      Parameters:
        `allowed` - true if projection is allowed

    - #### isDocumentProjectionAllowed

          public boolean isDocumentProjectionAllowed()

      Ask whether document projection is allowed
      Returns:
        true if document projection is allowed

    - #### getPublicId

          public java.lang.String getPublicId()

      Return the public identifier for the current document event.

      The return value is the public identifier of the document entity or of the external parsed entity in which the markup that triggered the event appears.

      Specified by:
        `getPublicId` in interface `Location`
      Specified by:
        `getPublicId` in interface `org.xml.sax.Locator`
      Specified by:
        `getPublicId` in interface `javax.xml.transform.SourceLocator`
      Returns:
        A string containing the public identifier, or null if none is available.
      See Also:
        `getSystemId()`

    - #### getSystemId

          public java.lang.String getSystemId()

      Return the system identifier for the current document event.

      The return value is the system identifier of the document entity or of the external parsed entity in which the markup that triggered the event appears.

      If the system identifier is a URL, the parser must resolve it fully before passing it to the application.

      Specified by:
        `getSystemId` in interface `Location`
      Specified by:
        `getSystemId` in interface `org.xml.sax.Locator`
      Specified by:
        `getSystemId` in interface `javax.xml.transform.SourceLocator`
      Returns:
        A string containing the system identifier, or null if none is available.
      See Also:
        `getPublicId()`

    - #### getLineNumber

          public int getLineNumber()

      Return the line number where the current document event ends.

      Warning: The return value from the method is intended only as an approximation for the sake of error reporting; it is not intended to provide sufficient information to edit the character content of the original XML document.

      The return value is an approximation of the line number in the document entity or external parsed entity where the markup that triggered the event appears.

      Specified by:
        `getLineNumber` in interface `Location`
      Specified by:
        `getLineNumber` in interface `org.xml.sax.Locator`
      Specified by:
        `getLineNumber` in interface `javax.xml.transform.SourceLocator`
      Returns:
        The line number, or -1 if none is available.
      See Also:
        `getColumnNumber()`

    - #### getColumnNumber

          public int getColumnNumber()

      Return the character position where the current document event ends.

      Warning: The return value from the method is intended only as an approximation for the sake of error reporting; it is not intended to provide sufficient information to edit the character content of the original XML document.

      The return value is an approximation of the column number in the document entity or external parsed entity where the markup that triggered the event appears.

      Specified by:
        `getColumnNumber` in interface `Location`
      Specified by:
        `getColumnNumber` in interface `org.xml.sax.Locator`
      Specified by:
        `getColumnNumber` in interface `javax.xml.transform.SourceLocator`
      Returns:
        The column number, or -1 if none is available.
      See Also:
        `getLineNumber()`

    - #### saveLocation

          public Location saveLocation()

      Get an immutable copy of this Location object. By default Location objects may be mutable, so they should not be saved for later use. The result of this operation holds the same location information, but in an immutable form.
      Specified by:
        `saveLocation` in interface `Location`
      Returns:
        an immutable copy (which may be the original object, if it is already immutable)

    - #### getHostLanguage

          public HostLanguage getHostLanguage()

      Get the host language (XSLT, XQuery, XPath) used to implement the code in this container
      Returns:
        `HostLanguage.XQUERY`

    - #### setChildExpression

          public void setChildExpression​(Expression expr)

      Specified by:
        `setChildExpression` in interface `ExpressionOwner`