## javax.xml.xquery
Interface XQConnection

All Superinterfaces:
  XQDataFactory

All Known Implementing Classes:
  SaxonXQConnection

    public interface XQConnection

extends XQDataFactory

A connection (session) with a specific XQuery engine. Connections are obtained through an `XQDataSource` object.

XQuery expressions are executed and results are returned within the context of a connection. They are either executed through `XQExpression` or `XQPreparedExpression` objects.

      XQDataSource ds;// obtain the XQuery datasource
      ...
      XQConnection conn = ds.getConnection();

      XQPreparedExpression expr = conn.prepareExpression("for $i in ...");
      XQResultSequence result = expr.executeQuery();
      // - or -
      XQExpression expr = conn.createExpression();
      XQSequence result = expr.executeQuery("for $i in..");

      // The sequence can now be iterated
      while (result.next())
      {
         String str  = result.getItemAsString();
         System.out.println(" output "+ str);
      }
      result.close();
      expr.close();
      conn.close();  // close the connection and free all resources..

A connection holds also default values for `XQExpression` and `XQPreparedExpression` properties. An application can override these defaults by passing an `XQStaticContext` object to the `setStaticContext()` method.

By default a connection operates in auto-commit mode, which means that each xquery is executed and committed in an individual transaction. If auto-commit mode is disabled, a transaction must be ended explicitly by the application calling `commit()` or `rollback()`.

An `XQConnection` object can be created on top of an existing JDBC connection. If an `XQConnection` is created on top of the JDBC connection, it inherits the transaction context from the JDBC connection. Also, in this case, if the auto-commit mode is changed, or a transaction is ended using commit or rollback, it also changes the underlying JDBC connection.

An XQJ driver is not required to provide finalizer methods for the connection and other objects. Hence it is strongly recommended that users call close method explicitly to free any resources. It is also recommended that they do so under a final block to ensure that the object is closed even when there are exceptions. Not closing this object explicitly might result in serious memory leaks.

When the `XQConnection` is closed any `XQExpression` and `XQPreparedExpression` objects obtained from it are also implicitly closed.

Method Summary
`void` `close()` Closes the connection.
`void` `commit()` Makes all changes made in the current transaction permanent and releases any locks held by the datasource.
`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
`XQMetaData` `getMetaData()` Gets the metadata for this connection.
`XQStaticContext` `getStaticContext()` Gets an `XQStaticContext` representing the default values for all expression properties.
`boolean` `isClosed()` Checks if the connection is closed.
`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 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

### close

    void close()
               throws XQException

  Closes the connection. This also closes any `XQExpression` and `XQPreparedExpression` obtained from this connection. Once the connection is closed, no method other than `close` or the `isClosed` method may be called on the connection object. Calling close on an `XQConnection` object that is already closed has no effect. Note that an XQJ driver is not required to provide finalizer methods for the connection and other objects. Hence it is strongly recommended that users call this method explicitly to free any resources. It is also recommended that they do so under a final block to ensure that the object is closed even when there are exceptions.

  Throws:
    `XQException` - if there is an error during closing the connection.

### setAutoCommit

    void setAutoCommit(boolean autoCommit)
                       throws XQException

  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.

  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

### getAutoCommit

    boolean getAutoCommit()
                          throws XQException

  Gets the auto-commit attribute of this connection

  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

### commit

    void commit()
                throws XQException

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

  Throws:
    `XQException` - if the connection is in a closed state or this connection is operating in auto-commit mode

### createExpression

    XQExpression createExpression()
                                  throws XQException

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

  Returns:
    `XQExpression` that can be used to execute multiple expressions
  Throws:
    `XQException` - if the connection is in a closed state

### createExpression

    XQExpression createExpression(XQStaticContext properties)
                                  throws XQException

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

  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`

### getMetaData

    XQMetaData getMetaData()
                           throws XQException

  Gets the metadata for this connection.

  Returns:
    `XQMetadata` representing the metadata of this connection
  Throws:
    `XQException` - if the connection is in a closed state

### isClosed

    boolean isClosed()

  Checks if the connection is closed.

  Returns:
    `true` if the connection is in a closed state, `false` otherwise

### prepareExpression

    XQPreparedExpression prepareExpression(String xquery)
                                           throws XQException

  Prepares an expression for execution.

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

  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

    XQPreparedExpression prepareExpression(String xquery,
                                           XQStaticContext properties)
                                           throws XQException

  Prepares an expression for execution.

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

  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`

### prepareExpression

    XQPreparedExpression prepareExpression(Reader xquery)
                                           throws XQException

  Prepares an expression for execution.

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

  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

    XQPreparedExpression prepareExpression(Reader xquery,
                                           XQStaticContext properties)
                                           throws XQException

  Prepares an expression for execution.

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

  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

    XQPreparedExpression prepareExpression(InputStream xquery)
                                           throws XQException

  Prepares an expression for execution.

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

  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

    XQPreparedExpression prepareExpression(InputStream xquery,
                                           XQStaticContext properties)
                                           throws XQException

  Prepares an expression for execution.

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

  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`

### rollback

    void rollback()
                  throws XQException

  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.

  Throws:
    `XQException` - if the connection is in a closed state or this connection is operating in auto-commit mode

### getStaticContext

    XQStaticContext getStaticContext()
                                     throws XQException

  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.

  Returns:
    `XQStaticContext` representing the default values for all expression properties
  Throws:
    `XQException` - if the connection is in a closed state

### setStaticContext

    void setStaticContext(XQStaticContext properties)
                          throws XQException

  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.

  Parameters:
    `properties` - `XQStaticContext` containing values of expression properties
  Throws:
    `XQException` - if the connection is in a closed state

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