Package org.firebirdsql.jaybird.xca

## Class FBManagedConnection

- java.lang.Object
- - org.firebirdsql.jaybird.xca.FBManagedConnection

- All Implemented Interfaces:
    `ExceptionListener`

      public final class FBManagedConnection
      extends java.lang.Object
      implements ExceptionListener

  A physical connection handle to a Firebird database, providing a `XAResource`.
  Author:
    David Jencks, Mark Rotteveel

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static java.lang.String` | `ERROR_NO_CHARSET` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addConnectionEventListener​(XcaConnectionEventListener listener)` | Add an `XcaConnectionEventListener` listener.
    `void` | `cleanup()` | Application server calls this method to force any cleanup on the managed connection instance.
    `void` | `close​(FBConnection c)` | Close this connection with regard to a wrapping `AbstractConnection`.
    `void` | `destroy()` | Destroys the physical connection to the underlying resource manager.
    `void` | `destroy​(XcaConnectionEvent connectionEvent)` |
    `void` | `errorOccurred​(java.lang.Object source, java.sql.SQLException ex)` | Notify about a SQLException
    `FBConnection` | `getConnection()` | Creates a new connection handle for the underlying physical connection represented by the managed connection instance.
    `FBConnectionRequestInfo` | `getConnectionRequestInfo()` | Get information about the current connection parameters.
    `java.lang.String` | `getDatabase()` | Deprecated. Will be removed in Jaybird 6; there is no direction replacement
    `GDSHelper` | `getGDSHelper()` | Get instance of `GDSHelper` connected with this managed connection.
    `FBLocalTransaction` | `getLocalTransaction()` | Returns a `FBLocalTransaction` instance.
    `FBManagedConnectionFactory` | `getManagedConnectionFactory()` | Get the managed connection factory that created this managed connection.
    `int` | `getTransactionIsolation()` | Get the transaction isolation level of this connection.
    `TransactionParameterBuffer` | `getTransactionParameters()` |
    `TransactionParameterBuffer` | `getTransactionParameters​(int isolation)` |
    `javax.transaction.xa.XAResource` | `getXAResource()` | Returns an `javax.transaction.xa.XAResource` instance.
    `boolean` | `inDistributedTransaction()` |
    `void` | `internalStart​(javax.transaction.xa.Xid id, int flags)` | Perform the internal processing to start associate a JDBC connection with a global transaction.
    `boolean` | `inTransaction()` |
    `boolean` | `isLockedByCurrentThread()` |
    `boolean` | `isManagedEnvironment()` |
    `boolean` | `isReadOnly()` | Retrieve whether this connection is readonly.
    `void` | `removeConnectionEventListener​(XcaConnectionEventListener listener)` | Remove a `XcaConnectionEventListener` from the listing of listeners that will be notified for a `XcaConnectionEvent`.
    `void` | `setManagedEnvironment​(boolean managedEnvironment)` |
    `void` | `setReadOnly​(boolean readOnly)` | Set whether this connection is to be readonly
    `void` | `setTransactionIsolation​(int isolation)` | Set the transaction level for this connection.
    `void` | `setTransactionParameters​(int isolation, TransactionParameterBuffer transactionParams)` |
    `void` | `setTransactionParameters​(TransactionParameterBuffer transactionParameters)` |
    `LockCloseable` | `withLock()` |

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

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

- - ### Field Detail

    - #### ERROR_NO_CHARSET

          public static final java.lang.String ERROR_NO_CHARSET

      See Also:
        Constant Field Values

  - ### Method Detail

    - #### errorOccurred

          public void errorOccurred​(java.lang.Object source,
                                    java.sql.SQLException ex)

      Description copied from interface: `ExceptionListener`
      Notify about a SQLException
      Specified by:
        `errorOccurred` in interface `ExceptionListener`
      Parameters:
        `source` - The source of the event; note for caller: this should be the object this listener is registered at.
        `ex` - error that occurred.

    - #### getGDSHelper

          public GDSHelper getGDSHelper()
                                 throws java.sql.SQLException

      Get instance of `GDSHelper` connected with this managed connection.
      Returns:
        instance of `GDSHelper`.
      Throws:
        `java.sql.SQLException` - If this connection has no GDSHelper

    - #### getDatabase

          @Deprecated
          public java.lang.String getDatabase()

      Deprecated.
      Will be removed in Jaybird 6; there is no direction replacement
      Returns the `databaseName` property as configured on the `ManagedConnectionFactory`.
      Returns:
        database name

    - #### isManagedEnvironment

          public boolean isManagedEnvironment()

    - #### inTransaction

          public boolean inTransaction()

    - #### setManagedEnvironment

          public void setManagedEnvironment​(boolean managedEnvironment)
                                     throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### getLocalTransaction

          public FBLocalTransaction getLocalTransaction()

      Returns a `FBLocalTransaction` instance.

      The FBLocalTransaction is used by the container to manage local transactions for a RM instance.

      Returns:
        FBLocalTransaction instance

    - #### addConnectionEventListener

          public void addConnectionEventListener​(XcaConnectionEventListener listener)

      Add an `XcaConnectionEventListener` listener. The listener will be notified when a `XcaConnectionEvent` occurs.
      Parameters:
        `listener` - The `XcaConnectionEventListener` to be added

    - #### removeConnectionEventListener

          public void removeConnectionEventListener​(XcaConnectionEventListener listener)

      Remove a `XcaConnectionEventListener` from the listing of listeners that will be notified for a `XcaConnectionEvent`.
      Parameters:
        `listener` - The `FirebirdConnectionEventListener` to be removed

    - #### cleanup

          public void cleanup()
                       throws java.sql.SQLException

      Application server calls this method to force any cleanup on the managed connection instance.

      The method `cleanup` initiates a cleanup of the any client-specific state as maintained by a managed connection instance. The cleanup should invalidate all connection handles that had been created using this managed connection instance. Any attempt by an application component to use the connection handle after cleanup of the underlying managed connection should result in an exception.

      The cleanup of managed connection is always driven by an application server. An application server should not invoke `cleanup` when there is an uncompleted transaction (associated with a managed connection instance) in progress.

      The invocation of the `cleanup` method on an already cleaned-up connection should not throw an exception.

      The cleanup of a managed connection instance resets its client specific state and prepares the connection to be put back in to a connection pool. The cleanup method should not cause resource adapter to close the physical pipe and reclaim system resources associated with the physical connection.

      Throws:
        `java.sql.SQLException` - generic exception if operation fails

    - #### getConnection

          public FBConnection getConnection()
                                     throws java.sql.SQLException

      Creates a new connection handle for the underlying physical connection represented by the managed connection instance. This connection handle is used by the application code to refer to the underlying physical connection.
      Returns:
        instance representing the connection handle
      Throws:
        `java.sql.SQLException` - generic exception if operation fails

    - #### destroy

          public void destroy()
                       throws java.sql.SQLException

      Destroys the physical connection to the underlying resource manager.

      To manage the size of the connection pool, an application server can explicitly call `destroy` to destroy a physical connection. A resource adapter should destroy all allocated system resources for this managed connection instance when the method destroy is called.

      Throws:
        `java.sql.SQLException` - generic exception if operation failed

    - #### destroy

          public void destroy​(XcaConnectionEvent connectionEvent)
                       throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### getXAResource

          public javax.transaction.xa.XAResource getXAResource()

      Returns an `javax.transaction.xa.XAResource` instance. An application server enlists this XAResource instance with the Transaction Manager if the FBManagedConnection instance is being used in a Java EE transaction that is coordinated by the Transaction Manager.
      Returns:
        XAResource instance

    - #### withLock

          public LockCloseable withLock()

      See Also:
        `FbAttachment.withLock()`

    - #### isLockedByCurrentThread

          public boolean isLockedByCurrentThread()

      See Also:
        `FbAttachment.isLockedByCurrentThread()`

    - #### inDistributedTransaction

          public boolean inDistributedTransaction()

    - #### internalStart

          public void internalStart​(javax.transaction.xa.Xid id,
                                    int flags)
                             throws javax.transaction.xa.XAException,
                                    java.sql.SQLException

      Perform the internal processing to start associate a JDBC connection with a global transaction.
      Parameters:
        `id` - A global transaction identifier to be associated with the resource
        `flags` - One of TMNOFLAGS, TMJOIN, or TMRESUME
      Throws:
        `javax.transaction.xa.XAException` - If the transaction is already started, or this connection cannot participate in the distributed transaction
        `java.sql.SQLException`
      See Also:
        `start(Xid, int)`

    - #### close

          public void close​(FBConnection c)

      Close this connection with regard to a wrapping `AbstractConnection`.
      Parameters:
        `c` - The `AbstractConnection` that is being closed

    - #### getConnectionRequestInfo

          public FBConnectionRequestInfo getConnectionRequestInfo()

      Get information about the current connection parameters.
      Returns:
        instance of `FBConnectionRequestInfo`.

    - #### getTransactionParameters

          public TransactionParameterBuffer getTransactionParameters()

    - #### setTransactionParameters

          public void setTransactionParameters​(TransactionParameterBuffer transactionParameters)

    - #### getTransactionParameters

          public TransactionParameterBuffer getTransactionParameters​(int isolation)

    - #### setTransactionParameters

          public void setTransactionParameters​(int isolation,
                                               TransactionParameterBuffer transactionParams)
                                        throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### getTransactionIsolation

          public int getTransactionIsolation()
                                      throws java.sql.SQLException

      Get the transaction isolation level of this connection. The level is one of the static final fields of `java.sql.Connection` (i.e. `TRANSACTION_READ_COMMITTED`, `TRANSACTION_READ_UNCOMMITTED`, `TRANSACTION_REPEATABLE_READ`, `TRANSACTION_SERIALIZABLE`.
      Returns:
        Value representing a transaction isolation level defined in `Connection`.
      Throws:
        `java.sql.SQLException` - If the transaction level cannot be retrieved
      See Also:
        `Connection`, `setTransactionIsolation(int)`

    - #### setTransactionIsolation

          public void setTransactionIsolation​(int isolation)
                                       throws java.sql.SQLException

      Set the transaction level for this connection. The level is one of the static final fields of `java.sql.Connection` (i.e. `TRANSACTION_READ_COMMITTED`, `TRANSACTION_READ_UNCOMMITTED`, `TRANSACTION_REPEATABLE_READ`, `TRANSACTION_SERIALIZABLE`.
      Parameters:
        `isolation` - Value representing a transaction isolation level defined in `Connection`.
      Throws:
        `java.sql.SQLException` - If the transaction level cannot be retrieved
      See Also:
        `Connection`, `getTransactionIsolation()`

    - #### getManagedConnectionFactory

          public FBManagedConnectionFactory getManagedConnectionFactory()

      Get the managed connection factory that created this managed connection.
      Returns:
        instance of `FBManagedConnectionFactory`.

    - #### setReadOnly

          public void setReadOnly​(boolean readOnly)

      Set whether this connection is to be readonly
      Parameters:
        `readOnly` - If `true`, the connection will be set read-only, otherwise it will be writable

    - #### isReadOnly

          public boolean isReadOnly()

      Retrieve whether this connection is readonly.
      Returns:
        `true` if this connection is readonly, `false` otherwise