Module org.firebirdsql.jaybird
Package org.firebirdsql.jaybird.xca

# Class FBManagedConnection

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

All Implemented Interfaces:
  `ExceptionListener`

public final class FBManagedConnection extends Object implements ExceptionListener
A physical connection handle to a Firebird database, providing a `XAResource`.

Author:
  David Jencks, Mark Rotteveel

- ## Method Summary

  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(Object source, 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.
  `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)`
  `XAResource`
  `getXAResource()`
  Returns an `javax.transaction.xa.XAResource` instance.
  `boolean`
  `inDistributedTransaction()`
  `void`
  `internalStart(Xid id, int flags)`
  Perform the internal processing to start associate a JDBC connection with a global transaction.
  `void`
  `internalStart(Xid xid, String sql)`
  Starts a transaction defined by `setTransactionSql`, and associate it with a JDBC connection.
  `boolean`
  `inTransaction()`
  `boolean`
  `isLockedByCurrentThread()`
  `boolean`
  `isManagedEnvironment()`
  `boolean`
  `isTpbAutoCommit()`
  Returns if the current TPB has the auto-commit flag set.
  `boolean`
  `isTpbReadOnly()`
  Retrieve whether the current TPB is read-only.
  `void`
  `removeConnectionEventListener(XcaConnectionEventListener listener)`
  Remove a `XcaConnectionEventListener` from the listing of listeners that will be notified for a `XcaConnectionEvent`.
  `void`
  `setManagedEnvironment(boolean managedEnvironment)`
  `void`
  `setTpbAutoCommit(boolean autoCommit)`
  Sets the Firebird auto-commit flag on the current TPB.
  `void`
  `setTpbReadOnly(boolean readOnly)`
  Set the current TPB to read-only.
  `void`
  `setTransactionIsolation(int isolation)`
  Set the transaction level for this connection.
  `void`
  `setTransactionParameters(int isolation, TransactionParameterBuffer transactionParams)`
  `void`
  `setTransactionParameters(TransactionParameterBuffer transactionParams)`
  Sets the current TPB to a copy of `transactionParams`.
  `LockCloseable`
  `withLock()`

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

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

- ## Method Details

  - ### errorOccurred

    public void errorOccurred(Object source, 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 SQLException
    Get instance of `GDSHelper` connected with this managed connection.
    Returns:
      instance of `GDSHelper`.
    Throws:
      `SQLException` - If this connection has no GDSHelper

  - ### isManagedEnvironment

    public boolean isManagedEnvironment()

  - ### inTransaction

    public boolean inTransaction()

  - ### setManagedEnvironment

    public void setManagedEnvironment(boolean managedEnvironment) throws SQLException
    Throws:
      `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 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:
      `SQLException` - generic exception if operation fails

  - ### getConnection

    public FBConnection getConnection() throws 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:
      `SQLException` - generic exception if operation fails

  - ### destroy

    public void destroy() throws 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:
      `SQLException` - generic exception if operation failed

  - ### destroy

    public void destroy(XcaConnectionEvent connectionEvent) throws SQLException
    Throws:
      `SQLException`

  - ### getXAResource

    public 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(Xid id, int flags) throws XAException, 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:
      `XAException` - If the transaction is already started, or this connection cannot participate in the distributed transaction
      `SQLException`
    See Also:
      - `start(Xid, int)`

  - ### internalStart

    public void internalStart(Xid xid, String sql) throws XAException, SQLException
    Starts a transaction defined by `setTransactionSql`, and associate it with a JDBC connection.
    Parameters:
      `xid` - global transaction identifier to be associated with the resource
      `sql` - `SET TRANSACTION` statement text
    Throws:
      `XAException` - if this connection cannot participate in the distributed transaction
      `SQLException` - for database access errors

  - ### 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()
    Returns:
      a copy of the current TPB

  - ### setTransactionParameters

    public void setTransactionParameters(TransactionParameterBuffer transactionParams)
    Sets the current TPB to a copy of `transactionParams`.
    Parameters:
      `transactionParams` - transaction parameters

  - ### getTransactionParameters

    public TransactionParameterBuffer getTransactionParameters(int isolation)

  - ### setTransactionParameters

    public void setTransactionParameters(int isolation, TransactionParameterBuffer transactionParams) throws SQLException
    Throws:
      `SQLException`

  - ### getTransactionIsolation

    public int getTransactionIsolation() throws 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:
      `SQLException` - If the transaction level cannot be retrieved
    See Also:
      - `Connection`
      - `setTransactionIsolation(int)`

  - ### setTransactionIsolation

    public void setTransactionIsolation(int isolation) throws 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:
      `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`.

  - ### setTpbReadOnly

    public void setTpbReadOnly(boolean readOnly)
    Set the current TPB to read-only.
    Parameters:
      `readOnly` - if `true`, the connection will be set read-only, otherwise it will be writable
    Since:
      6

  - ### isTpbReadOnly

    public boolean isTpbReadOnly()
    Retrieve whether the current TPB is read-only.
    Returns:
      `true` if this connection is readonly, `false` otherwise
    Since:
      6

  - ### setTpbAutoCommit

    public void setTpbAutoCommit(boolean autoCommit)
    Sets the Firebird auto-commit flag on the current TPB. This change is transient and will be reset when the transaction isolation level is set again or the TPB is otherwise replaced.

    This shouldn't be confused with the normal JDBC auto-commit behavior. Effectively, setting this to `true` will result in Firebird using commit retain after each executed statement.

    Parameters:
      `autoCommit` - `true` add the auto-commit flag, otherwise remove it
    Since:
      6
    See Also:
      - `isTpbAutoCommit()`

  - ### isTpbAutoCommit

    public boolean isTpbAutoCommit()
    Returns if the current TPB has the auto-commit flag set.
    Returns:
      `true` if the current TPB has the auto-commit flag, `false` otherwise
    Since:
      6
    See Also:
      - `setTpbAutoCommit(boolean)`