Package org.apache.commons.dbcp2.managed

# Class ManagedConnection<C extends Connection>

java.lang.Object
org.apache.commons.dbcp2.AbandonedTrace
org.apache.commons.dbcp2.DelegatingConnection<C>
org.apache.commons.dbcp2.managed.ManagedConnection<C>

Type Parameters:
  `C` - the Connection type

All Implemented Interfaces:
  `AutoCloseable`, `Connection`, `Wrapper`, `TrackedUse`

public class ManagedConnection<C extends Connection> extends DelegatingConnection<C>
ManagedConnection is responsible for managing a database connection in a transactional environment (typically called "Container Managed"). A managed connection operates like any other connection when no global transaction (a.k.a. XA transaction or JTA Transaction) is in progress. When a global transaction is active a single physical connection to the database is used by all ManagedConnections accessed in the scope of the transaction. Connection sharing means that all data access during a transaction has a consistent view of the database. When the global transaction is committed or rolled back the enlisted connections are committed or rolled back. Typically, upon transaction completion, a connection returns to the auto commit setting in effect before being enlisted in the transaction, but some vendors do not properly implement this.

When enlisted in a transaction the setAutoCommit(), commit(), rollback(), and setReadOnly() methods throw a SQLException. This is necessary to assure that the transaction completes as a single unit.

Since:
  2.0

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `protected class`
  `ManagedConnection.CompletionListener`
  Delegates to `transactionComplete()` for transaction completion events.

- ## Field Summary

  ### Fields inherited from interface java.sql.Connection

  `TRANSACTION_NONE, TRANSACTION_READ_COMMITTED, TRANSACTION_READ_UNCOMMITTED, TRANSACTION_REPEATABLE_READ, TRANSACTION_SERIALIZABLE`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ManagedConnection(ObjectPool<C> pool, TransactionRegistry transactionRegistry, boolean accessToUnderlyingConnectionAllowed)`
  Constructs a new instance responsible for managing a database connection in a transactional environment.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected void`
  `checkOpen()`
  Throws a SQLException if this connection is not open.
  `void`
  `close()`
  Closes the underlying connection, and close any Statements that were not explicitly closed.
  `void`
  `commit()`
  `C`
  `getDelegate()`
  Returns my underlying `Connection`.
  `Connection`
  `getInnermostDelegate()`
  If my underlying `Connection` is not a `DelegatingConnection`, returns it, otherwise recursively invokes this method on my delegate.
  `TransactionContext`
  `getTransactionContext()`
  Gets the transaction context.
  `TransactionRegistry`
  `getTransactionRegistry()`
  Gets the transaction registry.
  `boolean`
  `isAccessToUnderlyingConnectionAllowed()`
  If false, getDelegate() and getInnermostDelegate() will return null.
  `void`
  `rollback()`
  `void`
  `setAutoCommit(boolean autoCommit)`
  `void`
  `setReadOnly(boolean readOnly)`
  `protected void`
  `transactionComplete()`
  Completes the transaction.

  ### Methods inherited from class org.apache.commons.dbcp2.DelegatingConnection

  `abort, activate, clearCachedState, clearWarnings, closeInternal, createArrayOf, createBlob, createClob, createNClob, createSQLXML, createStatement, createStatement, createStatement, createStruct, getAutoCommit, getCacheState, getCatalog, getClientInfo, getClientInfo, getDefaultQueryTimeout, getDefaultQueryTimeoutDuration, getDelegateInternal, getHoldability, getInnermostDelegateInternal, getMetaData, getNetworkTimeout, getSchema, getTransactionIsolation, getTypeMap, getWarnings, handleException, handleExceptionNoThrow, innermostDelegateEquals, isClosed, isClosedInternal, isReadOnly, isValid, isValid, isWrapperFor, nativeSQL, passivate, prepareCall, prepareCall, prepareCall, prepareStatement, prepareStatement, prepareStatement, prepareStatement, prepareStatement, prepareStatement, releaseSavepoint, rollback, setCacheState, setCatalog, setClientInfo, setClientInfo, setClosedInternal, setDefaultQueryTimeout, setDefaultQueryTimeout, setDelegate, setHoldability, setNetworkTimeout, setSavepoint, setSavepoint, setSchema, setTransactionIsolation, setTypeMap, toString, unwrap`

  ### Methods inherited from class org.apache.commons.dbcp2.AbandonedTrace

  `addTrace, clearTrace, close, getLastUsed, getLastUsedInstant, getTrace, removeThisTrace, removeTrace, setLastUsed, setLastUsed, setLastUsed`

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

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

- ## Constructor Details

  - ### ManagedConnection

    public ManagedConnection(ObjectPool<C> pool, TransactionRegistry transactionRegistry, boolean accessToUnderlyingConnectionAllowed) throws SQLException
    Constructs a new instance responsible for managing a database connection in a transactional environment.
    Parameters:
      `pool` - The connection pool.
      `transactionRegistry` - The transaction registry.
      `accessToUnderlyingConnectionAllowed` - Whether or not to allow access to the underlying Connection.
    Throws:
      `SQLException` - Thrown when there is problem managing transactions.

- ## Method Details

  - ### checkOpen

    protected void checkOpen() throws SQLException
    Description copied from class: `DelegatingConnection`
    Throws a SQLException if this connection is not open.
    Overrides:
      `checkOpen` in class `DelegatingConnection<C extends Connection>`
    Throws:
      `SQLException` - Thrown if this connection is not open.

  - ### close

    public void close() throws SQLException
    Description copied from class: `DelegatingConnection`
    Closes the underlying connection, and close any Statements that were not explicitly closed. Sub-classes that override this method must:
    1. Call `DelegatingConnection.passivate()`
    2. Call close (or the equivalent appropriate action) on the wrapped connection
    3. Set `closed` to `false`
    Specified by:
      `close` in interface `AutoCloseable`
    Specified by:
      `close` in interface `Connection`
    Overrides:
      `close` in class `DelegatingConnection<C extends Connection>`
    Throws:
      `SQLException` - Ignored here, for subclasses.

  - ### commit

    public void commit() throws SQLException
    Specified by:
      `commit` in interface `Connection`
    Overrides:
      `commit` in class `DelegatingConnection<C extends Connection>`
    Throws:
      `SQLException`

  - ### getDelegate

    public C getDelegate()
    Description copied from class: `DelegatingConnection`
    Returns my underlying `Connection`.
    Overrides:
      `getDelegate` in class `DelegatingConnection<C extends Connection>`
    Returns:
      my underlying `Connection`.

  - ### getInnermostDelegate

    public Connection getInnermostDelegate()
    Description copied from class: `DelegatingConnection`
    If my underlying `Connection` is not a `DelegatingConnection`, returns it, otherwise recursively invokes this method on my delegate.

    Hence this method will return the first delegate that is not a `DelegatingConnection`, or `null` when no non-`DelegatingConnection` delegate can be found by traversing this chain.

    This method is useful when you may have nested `DelegatingConnection`s, and you want to make sure to obtain a "genuine" `Connection`.

    Overrides:
      `getInnermostDelegate` in class `DelegatingConnection<C extends Connection>`
    Returns:
      innermost delegate.

  - ### getTransactionContext

    public TransactionContext getTransactionContext()
    Gets the transaction context.
    Returns:
      The transaction context.
    Since:
      2.6.0

  - ### getTransactionRegistry

    public TransactionRegistry getTransactionRegistry()
    Gets the transaction registry.
    Returns:
      The transaction registry.
    Since:
      2.6.0

  - ### isAccessToUnderlyingConnectionAllowed

    public boolean isAccessToUnderlyingConnectionAllowed()
    If false, getDelegate() and getInnermostDelegate() will return null.
    Returns:
      if false, getDelegate() and getInnermostDelegate() will return null

  - ### rollback

    public void rollback() throws SQLException
    Specified by:
      `rollback` in interface `Connection`
    Overrides:
      `rollback` in class `DelegatingConnection<C extends Connection>`
    Throws:
      `SQLException`

  - ### setAutoCommit

    public void setAutoCommit(boolean autoCommit) throws SQLException
    Specified by:
      `setAutoCommit` in interface `Connection`
    Overrides:
      `setAutoCommit` in class `DelegatingConnection<C extends Connection>`
    Throws:
      `SQLException`

  - ### setReadOnly

    public void setReadOnly(boolean readOnly) throws SQLException
    Specified by:
      `setReadOnly` in interface `Connection`
    Overrides:
      `setReadOnly` in class `DelegatingConnection<C extends Connection>`
    Throws:
      `SQLException`

  - ### transactionComplete

    protected void transactionComplete()
    Completes the transaction.