Package org.apache.tomcat.dbcp.dbcp2.managed

## Class ManagedConnection<C extends java.sql.Connection>

- java.lang.Object
- - org.apache.tomcat.dbcp.dbcp2.AbandonedTrace
  - - org.apache.tomcat.dbcp.dbcp2.DelegatingConnection<C>
    - - org.apache.tomcat.dbcp.dbcp2.managed.ManagedConnection<C>

- Type Parameters:
    `C` - the Connection type
  All Implemented Interfaces:
    `java.lang.AutoCloseable`, `java.sql.Connection`, `java.sql.Wrapper`, `TrackedUse`

      public class ManagedConnection<C extends java.sql.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

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected void` | `checkOpen()` |
    `void` | `close()` | Closes the underlying connection, and close any Statements that were not explicitly closed.
    `void` | `commit()` |
    `C` | `getDelegate()` | Returns my underlying `Connection`.
    `java.sql.Connection` | `getInnermostDelegate()` | If my underlying `Connection` is not a `DelegatingConnection`, returns it, otherwise recursively invokes this method on my delegate.
    `TransactionContext` | `getTransactionContext()` |
    `TransactionRegistry` | `getTransactionRegistry()` |
    `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.tomcat.dbcp.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.tomcat.dbcp.dbcp2.AbandonedTrace

      `addTrace, clearTrace, 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`

    - ### Methods inherited from interface java.sql.Connection

      `beginRequest, endRequest, setShardingKey, setShardingKey, setShardingKeyIfValid, setShardingKeyIfValid`

- - ### Constructor Detail

    - #### ManagedConnection

          public ManagedConnection​(ObjectPool<C> pool,
                                   TransactionRegistry transactionRegistry,
                                   boolean accessToUnderlyingConnectionAllowed)
                            throws java.sql.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:
        `java.sql.SQLException` - Thrown when there is problem managing transactions.

  - ### Method Detail

    - #### checkOpen

          protected void checkOpen()
                            throws java.sql.SQLException

      Overrides:
        `checkOpen` in class `DelegatingConnection<C extends java.sql.Connection>`
      Throws:
        `java.sql.SQLException`

    - #### close

          public void close()
                     throws java.sql.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 passivate()
      2. Call close (or the equivalent appropriate action) on the wrapped connection
      3. Set _closed to `false`
      Specified by:
        `close` in interface `java.lang.AutoCloseable`
      Specified by:
        `close` in interface `java.sql.Connection`
      Overrides:
        `close` in class `DelegatingConnection<C extends java.sql.Connection>`
      Throws:
        `java.sql.SQLException`

    - #### commit

          public void commit()
                      throws java.sql.SQLException

      Specified by:
        `commit` in interface `java.sql.Connection`
      Overrides:
        `commit` in class `DelegatingConnection<C extends java.sql.Connection>`
      Throws:
        `java.sql.SQLException`

    - #### getDelegate

          public C getDelegate()

      Description copied from class: `DelegatingConnection`
      Returns my underlying `Connection`.
      Overrides:
        `getDelegate` in class `DelegatingConnection<C extends java.sql.Connection>`
      Returns:
        my underlying `Connection`.

    - #### getInnermostDelegate

          public java.sql.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 java.sql.Connection>`
      Returns:
        innermost delegate.

    - #### getTransactionContext

          public TransactionContext getTransactionContext()

      Returns:
        The transaction context.
      Since:
        2.6.0

    - #### getTransactionRegistry

          public TransactionRegistry getTransactionRegistry()

      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 java.sql.SQLException

      Specified by:
        `rollback` in interface `java.sql.Connection`
      Overrides:
        `rollback` in class `DelegatingConnection<C extends java.sql.Connection>`
      Throws:
        `java.sql.SQLException`

    - #### setAutoCommit

          public void setAutoCommit​(boolean autoCommit)
                             throws java.sql.SQLException

      Specified by:
        `setAutoCommit` in interface `java.sql.Connection`
      Overrides:
        `setAutoCommit` in class `DelegatingConnection<C extends java.sql.Connection>`
      Throws:
        `java.sql.SQLException`

    - #### setReadOnly

          public void setReadOnly​(boolean readOnly)
                           throws java.sql.SQLException

      Specified by:
        `setReadOnly` in interface `java.sql.Connection`
      Overrides:
        `setReadOnly` in class `DelegatingConnection<C extends java.sql.Connection>`
      Throws:
        `java.sql.SQLException`

    - #### transactionComplete

          protected void transactionComplete()

      Completes the transaction.