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

## Class ManagedConnection<C extends 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:
  `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
`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
`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
`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`.
`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, 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`

### 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 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 Detail

#### checkOpen

    protected void checkOpen()
                      throws SQLException

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

#### 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()

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