Package com.saxonica.xqj

## Class SaxonXQPreparedExpression

- java.lang.Object
- - com.saxonica.xqj.Closable
  - - com.saxonica.xqj.SaxonXQDynamicContext
    - - com.saxonica.xqj.SaxonXQPreparedExpression

- All Implemented Interfaces:
    `XQDynamicContext`, `XQPreparedExpression`

      public class SaxonXQPreparedExpression
      extends SaxonXQDynamicContext
      implements XQPreparedExpression

  Saxon implementation of the XQJ interface XQPreparedExpression. This represents a compiled XQuery expression, together with the dynamic context for its evaluation. Note that this means the object should not be used in more than one thread concurrently.

  Note that an expression is scrollable or not depending on the scrollability property of the XQConnection that was used to compile this expression (at the time it was compiled). If the expression is scrollable then its results are delivered in an XQSequence that supports scrolling backwards as well as forwards.

  For full Javadoc details, see the XQJ interface specification.

- - ### Field Summary

    - ### Fields inherited from class com.saxonica.xqj.SaxonXQDynamicContext

      `connection`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `SaxonXQPreparedExpression​(SaxonXQConnection connection, XQueryExpression expression, SaxonXQStaticContext sqc, DynamicQueryContext context)` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `cancel()` | Attempts to cancel the execution if both the XQuery engine and XQJ driver support aborting the execution of an `XQPreparedExpression`.
    `XQResultSequence` | `executeQuery()` | Executes the prepared query expression.
    `protected boolean` | `externalVariableExists​(javax.xml.namespace.QName name)` |
    `javax.xml.namespace.QName[]` | `getAllExternalVariables()` | Retrieves all the external variables defined in the prolog of the prepared expression.
    `javax.xml.namespace.QName[]` | `getAllUnboundExternalVariables()` | Retrieves the names of all unbound external variables.
    `protected SaxonXQConnection` | `getConnection()` |
    `protected SaxonXQDataFactory` | `getDataFactory()` |
    `protected DynamicQueryContext` | `getDynamicContext()` |
    `protected SaxonXQStaticContext` | `getSaxonXQStaticContext()` |
    `XQStaticContext` | `getStaticContext()` | Gets an `XQStaticContext` representing the values for all expression properties.
    `XQSequenceType` | `getStaticResultType()` | Gets the static type information of the result sequence.
    `XQSequenceType` | `getStaticVariableType​(javax.xml.namespace.QName name)` | Retrieves the static type of a given external variable.
    `protected XQueryExpression` | `getXQueryExpression()` |

    - ### Methods inherited from class com.saxonica.xqj.SaxonXQDynamicContext

      `bindAtomicValue, bindBoolean, bindByte, bindDocument, bindDocument, bindDocument, bindDocument, bindDocument, bindDouble, bindFloat, bindInt, bindItem, bindLong, bindNode, bindObject, bindSequence, bindShort, bindString, getConfiguration, getImplicitTimeZone, setImplicitTimeZone`

    - ### Methods inherited from class com.saxonica.xqj.Closable

      `close, isClosed, setClosableContainer`

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

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

    - ### Methods inherited from interface javax.xml.xquery.XQDynamicContext

      `bindAtomicValue, bindBoolean, bindByte, bindDocument, bindDocument, bindDocument, bindDocument, bindDocument, bindDouble, bindFloat, bindInt, bindItem, bindLong, bindNode, bindObject, bindSequence, bindShort, bindString, getImplicitTimeZone, setImplicitTimeZone`

    - ### Methods inherited from interface javax.xml.xquery.XQPreparedExpression

      `close, isClosed`

- - ### Constructor Detail

    - #### SaxonXQPreparedExpression

          protected SaxonXQPreparedExpression​(SaxonXQConnection connection,
                                              XQueryExpression expression,
                                              SaxonXQStaticContext sqc,
                                              DynamicQueryContext context)
                                       throws XQException

      Throws:
        `XQException`

  - ### Method Detail

    - #### getDynamicContext

          protected DynamicQueryContext getDynamicContext()

      Specified by:
        `getDynamicContext` in class `SaxonXQDynamicContext`

    - #### getConnection

          protected SaxonXQConnection getConnection()

    - #### getDataFactory

          protected SaxonXQDataFactory getDataFactory()
                                               throws XQException

      Specified by:
        `getDataFactory` in class `SaxonXQDynamicContext`
      Throws:
        `XQException`

    - #### getXQueryExpression

          protected XQueryExpression getXQueryExpression()

    - #### getSaxonXQStaticContext

          protected SaxonXQStaticContext getSaxonXQStaticContext()

    - #### cancel

          public void cancel()
                      throws XQException

      Description copied from interface: `XQPreparedExpression`
      Attempts to cancel the execution if both the XQuery engine and XQJ driver support aborting the execution of an `XQPreparedExpression`. This method can be used by one thread to cancel an `XQPreparedExpression`, that is being executed in another thread. If cancellation is not supported or the attempt to cancel the execution was not successful, the method returns without any error. If the cancellation is successful, an `XQException` is thrown, to indicate that it has been aborted, by `executeQuery`, `executeCommand` or any method accessing the `XQResultSequence` returned by `executeQuery`. If applicable, any open `XQResultSequence` and `XQResultItem` objects will also be implicitly closed in this case.
      Specified by:
        `cancel` in interface `XQPreparedExpression`
      Throws:
        `XQException` - if the prepared expression is in a closed state

    - #### executeQuery

          public XQResultSequence executeQuery()
                                        throws XQException

      Description copied from interface: `XQPreparedExpression`
      Executes the prepared query expression. Calling this method implicitly closes any previous result sequence obtained from this expression.
      Specified by:
        `executeQuery` in interface `XQPreparedExpression`
      Returns:
        the xquery sequence object containing the result of the query execution
      Throws:
        `XQException` - if (1) there are errors when executing the prepared expression, (2) the prepared expression is in a closed state, or (3) the query execution is cancelled

    - #### getAllExternalVariables

          public javax.xml.namespace.QName[] getAllExternalVariables()
                                                              throws XQException

      Description copied from interface: `XQPreparedExpression`
      Retrieves all the external variables defined in the prolog of the prepared expression.
      Specified by:
        `getAllExternalVariables` in interface `XQPreparedExpression`
      Returns:
        an array of `QName` objects for all the external variables defined in the prolog of a prepared expression. Empty array if there are no external variables present.
      Throws:
        `XQException` - if the prepared expression is in a closed state

    - #### getAllUnboundExternalVariables

          public javax.xml.namespace.QName[] getAllUnboundExternalVariables()
                                                                     throws XQException

      Description copied from interface: `XQPreparedExpression`
      Retrieves the names of all unbound external variables.
      Specified by:
        `getAllUnboundExternalVariables` in interface `XQPreparedExpression`
      Returns:
        the `QName` for all the external variables defined in the prolog of a prepared expression that are yet to be bound with a value. If there are no such variables an empty array is returned
      Throws:
        `XQException` - if the prepared expression is in a closed state

    - #### getStaticContext

          public XQStaticContext getStaticContext()
                                           throws XQException

      Description copied from interface: `XQPreparedExpression`
      Gets an `XQStaticContext` representing the values for all expression properties. Note that these properties cannot be changed; in order to change, a new `XQPreparedExpression` needs to be created.
      Specified by:
        `getStaticContext` in interface `XQPreparedExpression`
      Returns:
        an `XQStaticContext` representing the values for all expression properties
      Throws:
        `XQException` - if the expression is in a closed state

    - #### getStaticResultType

          public XQSequenceType getStaticResultType()
                                             throws XQException

      Description copied from interface: `XQPreparedExpression`
      Gets the static type information of the result sequence. If an implementation does not do static typing of the query, then this method must return an `XQSequenceType` object corresponding to the XQuery sequence type `item()*`.
      Specified by:
        `getStaticResultType` in interface `XQPreparedExpression`
      Returns:
        `XQSequenceType` containing the static result information.
      Throws:
        `XQException` - if the prepared expression is in a closed state

    - #### getStaticVariableType

          public XQSequenceType getStaticVariableType​(javax.xml.namespace.QName name)
                                               throws XQException

      Description copied from interface: `XQPreparedExpression`
      Retrieves the static type of a given external variable.
      Specified by:
        `getStaticVariableType` in interface `XQPreparedExpression`
      Parameters:
        `name` - the name of the external variable
      Returns:
        the static type information of the variable as defined in the prolog of the prepared expression
      Throws:
        `XQException` - if (1) the variable does not exist in the static context of the expression, or (2) the sequence is in a closed state, or (3) the `name` parameter is `null`

    - #### externalVariableExists

          protected boolean externalVariableExists​(javax.xml.namespace.QName name)

      Specified by:
        `externalVariableExists` in class `SaxonXQDynamicContext`