## net.sf.saxon.query
Class XQueryExpression

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

All Implemented Interfaces:
  Container, javax.xml.transform.SourceLocator

public class XQueryExpression
extends java.lang.Object
implements Container

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

Constructor Summary
`protected` `XQueryExpression(Expression exp, Executable exec, StaticQueryContext staticEnv, Configuration config)` The constructor is protected, to ensure that instances can only be created using the compileQuery() methods of QueryProcessor

Method Summary
`java.util.List` `evaluate(DynamicQueryContext env)` Execute a the compiled Query, returning the results as a List.
`java.lang.Object` `evaluateSingle(DynamicQueryContext env)` Execute the compiled Query, returning the first item in the result.
`void` `explain(NamePool pool)` Diagnostic method: display a representation of the compiled query on the System.err output stream.
`int` `getColumnNumber()` Return the character position where the current document event ends.
`Controller` `getController()` Get a controller that can be used to execute functions in this compiled query.
`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
`int` `getLineNumber()` Return the line number where the current document event ends.
`java.lang.String` `getPublicId()` Return the public identifier for the current document event.
`java.lang.String` `getSystemId()` Return the system identifier for the current document event.
`SequenceIterator` `iterator(DynamicQueryContext env)` Get an iterator over the results of the expression.
`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.
`protected void` `setDocumentInstruction(DocumentInstr doc)`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### XQueryExpression

    protected XQueryExpression(Expression exp,
                               Executable exec,
                               StaticQueryContext staticEnv,
                               Configuration config)
                        throws XPathException

  The constructor is protected, to ensure that instances can only be created using the compileQuery() methods of QueryProcessor

Method Detail

### getExpression

    public Expression getExpression()

  Get the expression wrapped in this XQueryExpression object

  Returns:
    the underlying expression

### setDocumentInstruction

    protected void setDocumentInstruction(DocumentInstr doc)

### evaluate

    public java.util.List evaluate(DynamicQueryContext env)
                            throws XPathException

  Execute a the compiled Query, returning the results as a List.

  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 `evaluate` method of class XPathProcessor
    `XPathException`

### 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` method
    `XPathException`

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

  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.

### getController

    public Controller getController()

  Get a controller that can be used to execute functions in this compiled query. Functions in the query module can be found using `StaticQueryContext.getUserDefinedFunction(java.lang.String, java.lang.String, int)`. They can then be called directly from the Java application using `UserFunction.call(net.sf.saxon.value.Value[], net.sf.saxon.expr.XPathContextMajor, boolean)` The same Controller can be used for a series of function calls.

### explain

    public void explain(NamePool pool)

  Diagnostic method: display a representation of the compiled query on the System.err output stream.

### getExecutable

    public Executable getExecutable()

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

  Specified by:
    `getExecutable` in interface `Container`

### 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 `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 `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 `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 `javax.xml.transform.SourceLocator`
  Returns:
    The column number, or -1 if none is available.
  See Also:
    `getLineNumber()`