net.sf.saxon.xqj

## Class SaxonXQConnection

- java.lang.Object
- - net.sf.saxon.xqj.Closable
  - - net.sf.saxon.xqj.SaxonXQDataFactory
    - - net.sf.saxon.xqj.SaxonXQConnection

- All Implemented Interfaces:
    XQConnection, XQDataFactory

      public class SaxonXQConnection
      extends SaxonXQDataFactory
      implements XQConnection

  Saxon implementation of the XQL interface XQConnection. This interface represents a "connection" between an XQuery application and an XQuery server. In Saxon the client and server run in the same process so the concept of a connection is rather notional, and some of the properties have little meaning. However, the connection is the factory object used to compile queries.

  For Javadoc descriptions of the public methors, see the XQJ documentation.

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `commit()` Makes all changes made in the current transaction permanent and releases any locks held by the datasource.
    `XQPreparedExpression` | `copyPreparedExpression(XQPreparedExpression expression)` Copy a prepared expression to create a new prepared expression.
    `XQExpression` | `createExpression()` Creates a new `XQExpression` object that can be used to perform execute immediate operations with XQuery expressions.
    `XQExpression` | `createExpression(XQStaticContext properties)` Creates a new `XQExpression` object that can be used to perform execute immediate operations with XQuery expressions.
    `boolean` | `getAutoCommit()` Gets the auto-commit attribute of this connection
    `Configuration` | `getConfiguration()` Get the Saxon Configuration in use.
    `XQMetaData` | `getMetaData()` Gets the metadata for this connection.
    `XQStaticContext` | `getStaticContext()` Gets an `XQStaticContext` representing the default values for all expression properties.
    `XQPreparedExpression` | `prepareExpression(InputStream xquery)` Prepares an expression for execution.
    `XQPreparedExpression` | `prepareExpression(InputStream xquery, XQStaticContext properties)` Prepares an expression for execution.
    `XQPreparedExpression` | `prepareExpression(Reader xquery)` Prepares an expression for execution.
    `XQPreparedExpression` | `prepareExpression(Reader xquery, XQStaticContext properties)` Prepares an expression for execution.
    `XQPreparedExpression` | `prepareExpression(String xquery)` Prepares an expression for execution.
    `XQPreparedExpression` | `prepareExpression(String xquery, XQStaticContext properties)` Prepares an expression for execution.
    `void` | `rollback()` Undoes all changes made in the current transaction and releases any locks held by the datasource.
    `void` | `setAutoCommit(boolean autoCommit)` Sets the auto-commit attribute to the given state.
    `void` | `setStaticContext(XQStaticContext properties)` Sets the default values for all expression properties.

    - ### Methods inherited from class net.sf.saxon.xqj.SaxonXQDataFactory

      `createAtomicType, createAtomicType, createAttributeType, createAttributeType, createCommentType, createDocumentElementType, createDocumentSchemaElementType, createDocumentType, createElementType, createElementType, createItem, createItemFromAtomicValue, createItemFromBoolean, createItemFromByte, createItemFromDocument, createItemFromDocument, createItemFromDocument, createItemFromDocument, createItemFromDocument, createItemFromDouble, createItemFromFloat, createItemFromInt, createItemFromLong, createItemFromNode, createItemFromObject, createItemFromShort, createItemFromString, createItemType, createNodeType, createProcessingInstructionType, createSchemaAttributeType, createSchemaElementType, createSequence, createSequence, createSequenceType, createTextType, getObjectConverter, init, setObjectConverter`

    - ### Methods inherited from class net.sf.saxon.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.XQConnection

      `close, isClosed`

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

      `createAtomicType, createAtomicType, createAttributeType, createAttributeType, createCommentType, createDocumentElementType, createDocumentSchemaElementType, createDocumentType, createElementType, createElementType, createItem, createItemFromAtomicValue, createItemFromBoolean, createItemFromByte, createItemFromDocument, createItemFromDocument, createItemFromDocument, createItemFromDocument, createItemFromDocument, createItemFromDouble, createItemFromFloat, createItemFromInt, createItemFromLong, createItemFromNode, createItemFromObject, createItemFromShort, createItemFromString, createItemType, createNodeType, createProcessingInstructionType, createSchemaAttributeType, createSchemaElementType, createSequence, createSequence, createSequenceType, createTextType`

- - ### Method Detail

    - #### getConfiguration

          public Configuration getConfiguration()

      Get the Saxon Configuration in use. Changes made to this Configuration will affect this data source and XQJ connections created from it (either before or afterwards).
      Returns:
        the configuration in use.

    - #### commit

          public void commit()
                      throws XQException

      Description copied from interface: `XQConnection`
      Makes all changes made in the current transaction permanent and releases any locks held by the datasource. This method should be used only when auto-commit mode is disabled. Any `XQResultSequence`, or `XQResultItem` may be implicitly closed upon commit, if the holdability property of the sequence is set to `XQConstants.HOLDTYPE_CLOSE_CURSORS_AT_COMMIT`.
      Specified by:
        `commit` in interface `XQConnection`
      Throws:
        `XQException` - if the connection is in a closed state or this connection is operating in auto-commit mode

    - #### createExpression

          public XQExpression createExpression()
                                        throws XQException

      Description copied from interface: `XQConnection`
      Creates a new `XQExpression` object that can be used to perform execute immediate operations with XQuery expressions. The properties of the connection's default `XQStaticContext` are copied to the returned `XQExpression`.
      Specified by:
        `createExpression` in interface `XQConnection`
      Returns:
        `XQExpression` that can be used to execute multiple expressions
      Throws:
        `XQException` - if the connection is in a closed state

    - #### createExpression

          public XQExpression createExpression(XQStaticContext properties)
                                        throws XQException

      Description copied from interface: `XQConnection`
      Creates a new `XQExpression` object that can be used to perform execute immediate operations with XQuery expressions. The properties of the specified `XQStaticContext` values are copied to the returned `XQExpression`.
      Specified by:
        `createExpression` in interface `XQConnection`
      Parameters:
        `properties` - `XQStaticContext` containing values of expression properties
      Returns:
        `XQExpression` that can be used to execute multiple expressions
      Throws:
        `XQException` - if (1) the connection is in a closed state, or (2) the specified argument is `null`

    - #### getAutoCommit

          public boolean getAutoCommit()
                                throws XQException

      Description copied from interface: `XQConnection`
      Gets the auto-commit attribute of this connection
      Specified by:
        `getAutoCommit` in interface `XQConnection`
      Returns:
        the auto-commit attribute of this connection. `true` if the connection operates in auto-commit mode; otherwise `false`
      Throws:
        `XQException` - if the connection is in a closed state

    - #### getMetaData

          public XQMetaData getMetaData()
                                 throws XQException

      Description copied from interface: `XQConnection`
      Gets the metadata for this connection.
      Specified by:
        `getMetaData` in interface `XQConnection`
      Returns:
        `XQMetadata` representing the metadata of this connection
      Throws:
        `XQException` - if the connection is in a closed state

    - #### getStaticContext

          public XQStaticContext getStaticContext()
                                           throws XQException

      Description copied from interface: `XQConnection`
      Gets an `XQStaticContext` representing the default values for all expression properties. In order to modify the defaults, it is not sufficient to modify the values in the returned `XQStaticContext` object; in addition `setStaticContext` should be called to make those new values effective.
      Specified by:
        `getStaticContext` in interface `XQConnection`
      Returns:
        `XQStaticContext` representing the default values for all expression properties
      Throws:
        `XQException` - if the connection is in a closed state

    - #### prepareExpression

          public XQPreparedExpression prepareExpression(InputStream xquery)
                                                 throws XQException

      Description copied from interface: `XQConnection`
      Prepares an expression for execution.

      The properties of the connection's default `XQStaticContext` are copied to the returned `XQPreparedExpression`.

      Specified by:
        `prepareExpression` in interface `XQConnection`
      Parameters:
        `xquery` - the XQuery expression as an `InputStream`. Cannot be `null`
      Returns:
        the prepared XQuery expression
      Throws:
        `XQException` - if (1) the connection is in a closed state, (2) there are errors preparing the expression or (3) the xquery parameter is `null`

    - #### prepareExpression

          public XQPreparedExpression prepareExpression(InputStream xquery,
                                               XQStaticContext properties)
                                                 throws XQException

      Description copied from interface: `XQConnection`
      Prepares an expression for execution.

      The properties of the specified `XQStaticContext` values are copied to the returned `XQPreparedExpression`.

      Specified by:
        `prepareExpression` in interface `XQConnection`
      Parameters:
        `xquery` - the XQuery expression as an `InputStream`. Cannot be `null`
        `properties` - `XQStaticContext` containing values of expression properties
      Returns:
        the prepared XQuery expression
      Throws:
        `XQException` - if (1) the connection is in a closed state, or (2) the specified argument is `null`

    - #### prepareExpression

          public XQPreparedExpression prepareExpression(Reader xquery)
                                                 throws XQException

      Description copied from interface: `XQConnection`
      Prepares an expression for execution.

      The properties of the connection's default `XQStaticContext` are copied to the returned `XQPreparedExpression`.

      Specified by:
        `prepareExpression` in interface `XQConnection`
      Parameters:
        `xquery` - the XQuery expression as a `Reader`. Cannot be `null`
      Returns:
        the prepared XQuery expression
      Throws:
        `XQException` - if (1) the connection is in a closed state, (2) there are errors preparing the expression, or (3) the xquery parameter is `null`

    - #### prepareExpression

          public XQPreparedExpression prepareExpression(Reader xquery,
                                               XQStaticContext properties)
                                                 throws XQException

      Description copied from interface: `XQConnection`
      Prepares an expression for execution.

      The properties of the specified `XQStaticContext` values are copied to the returned `XQPreparedExpression`.

      Specified by:
        `prepareExpression` in interface `XQConnection`
      Parameters:
        `xquery` - the XQuery expression as a `Reader`. Cannot be `null`
        `properties` - `XQStaticContext` containing values of expression properties
      Returns:
        the prepared XQuery expression
      Throws:
        `XQException` - if (1) the connection is in a closed state, or (2) the specified argument is `null`

    - #### prepareExpression

          public XQPreparedExpression prepareExpression(String xquery)
                                                 throws XQException

      Description copied from interface: `XQConnection`
      Prepares an expression for execution.

      The properties of the connection's default `XQStaticContext` are copied to the returned `XQPreparedExpression`.

      Specified by:
        `prepareExpression` in interface `XQConnection`
      Parameters:
        `xquery` - the XQuery expression as a `String`. Cannot be `null`
      Returns:
        the prepared XQuery expression
      Throws:
        `XQException` - if (1) the connection is in a closed state, (2) there are errors preparing the expression, or (3) the xquery parameter is `null`

    - #### prepareExpression

          public XQPreparedExpression prepareExpression(String xquery,
                                               XQStaticContext properties)
                                                 throws XQException

      Description copied from interface: `XQConnection`
      Prepares an expression for execution.

      The properties of the specified `XQStaticContext` values are copied to the returned `XQPreparedExpression`.

      Specified by:
        `prepareExpression` in interface `XQConnection`
      Parameters:
        `xquery` - the XQuery expression as a `String`. Cannot be `null`
        `properties` - `XQStaticContext` containing values of expression properties.
      Returns:
        the prepared XQuery expression
      Throws:
        `XQException` - if (1) the connection is in a closed state, or (2) the specified argument is `null`

    - #### copyPreparedExpression

          public XQPreparedExpression copyPreparedExpression(XQPreparedExpression expression)
                                                      throws XQException

      Copy a prepared expression to create a new prepared expression. The prepared expression to be copied may belong to a different connection. This method (which is a Saxon extension to the XQJ interface) allows a query to be compiled once, and reused concurrently under multiple connections in multiple threads. The compiled code of the existing query and its static context are shared with the original query, but a new dynamic context is established, so that the two expressions can safely be used in parallel.
      Parameters:
        `expression` - the XQPreparedExpression to be copied. This must have been created using Saxon, and it must have been created with an XQConnection derived from the same XQDataSource as this connection.
      Returns:
        a copy of the supplied expression, that can be used in a different connection or thread with its own dynamic context. The new copy of the expression belongs to this connection, and can be used in the same way as an expression created using any of the prepareExpression() methods on this class.
      Throws:
        `XQException,` - for example if either of the connections has been closed
        `XQException`

    - #### rollback

          public void rollback()
                        throws XQException

      Description copied from interface: `XQConnection`
      Undoes all changes made in the current transaction and releases any locks held by the datasource. This method should be used only when auto-commit mode is disabled.
      Specified by:
        `rollback` in interface `XQConnection`
      Throws:
        `XQException` - if the connection is in a closed state or this connection is operating in auto-commit mode

    - #### setAutoCommit

          public void setAutoCommit(boolean autoCommit)
                             throws XQException

      Description copied from interface: `XQConnection`
      Sets the auto-commit attribute to the given state. If a connection is in auto-commit mode, each xquery is executed and committed in an individual transaction. When auto-commit mode is disabled, xqueries are grouped in a transaction that must be ended explicitly by the application calling `commit()` or `rollback()`.
      By default, new connections are in auto-commit mode.
      If the value of auto-commit is changed in the middle of a transaction, the transaction is committed. If `setAutoCommit` is called and the auto-commit attribute is not changed from its current value, the request is treated as a no-op.
      Specified by:
        `setAutoCommit` in interface `XQConnection`
      Parameters:
        `autoCommit` - `true` to enable auto-commit mode; `false` to disable it
      Throws:
        `XQException` - if (1) the connection is in a closed state, or (2) auto-commit is turned off but the implementation doesn't support transactions

    - #### setStaticContext

          public void setStaticContext(XQStaticContext properties)
                                throws XQException

      Description copied from interface: `XQConnection`
      Sets the default values for all expression properties. The implementation will read out all expression properties from the specified `XQStaticContext` and update its private copy.
      Specified by:
        `setStaticContext` in interface `XQConnection`
      Parameters:
        `properties` - `XQStaticContext` containing values of expression properties
      Throws:
        `XQException` - if the connection is in a closed state

Copyright (c) 2004-2013 Saxonica Limited. All rights reserved.