www.ironjacamar.orgCommunity Documentation

Chapter 8. Connection manager

Table of Contents

8.1. Overview
8.2. Public API
8.3. Private API
8.4. Implementation
8.4.1. AbstractConnectionManager
8.4.2. NoTxConnectionManagerImpl
8.4.3. TxConnectionManagerImpl
8.4.4. AbstractConnectionListener
8.4.5. NoTxConnectionListener
8.4.6. TxConnectionListener

8.1. Overview

The connection manager defines the interface for resource adapters to allocate connections, which are associated with the physical connections to the target Enterprise Information System, such as a database.

It is up to the connection manager to use the pool, and enlist the connection listeners in the transactions, if supported.

The connection manager architecture

Note

Each of the components in the connection manager architecture can be accessed by multiple threads at the same time, hence each component needs to make sure that thread safely is maintained.

8.2. Public API

The public API defines the API that programs external to the IronJacamar project can use to configure, and use the connection manager.

The ConnectionManager interface allows to associate and dissociate a managed connection with a connection.

The ConnectionListener interface provides with IronJacamar contract for javax.resource.spi.ConnectionEventListener.

The package for the public API is org.jboss.jca.core.api.connectionmanager.

8.3. Private API

The private API defines the API that can be used internally IronJacamar to control the connection manager. The API extends the public API where it makes sense in order to provide a more uniform interface to the implementation.

The ConnectionManagerFactory class can create a ConnectionManager instance.

The ConnectionManager interface defines the internal API of the connection manager used by IronJacamar.

The NoTxConnectionManager interface defines the internal API of a non-transactional connection manager.

The TxConnectionManager interface defines the internal API of a transactional connection manager.

The ConnectionListener interface defines the internal API of a connection listener, which is associated with a managed connection.

The package for the private API is org.jboss.jca.core.connectionmanager.

8.4. Implementation

The implementation of the connection manager is split in two classes, with a shared base class for common functionality.

AbstractConnectionManager provides the methods that are shared across both implementations, NoTxConnectionManagerImpl and TxConnectionManagerImpl.

getManagedConnection(Transaction, Subject, ConnectionRequestInfo) obtains a ConnectionListener instance from the pool. If an error occurs a retry is performed, if configured.

returnManagedConnection(ConnectionListener, boolean) returns a ConnectionListener instance to the pool. If an error occurs a retry is performed, if configured.

allocateConnection(ManagedConnectionFactory, ConnectionRequestInfo) allocates a connection for the managed connection attached to the ConnectionListener instance.

associateManagedConnection(Object, ManagedConnectionFactory, ConnectionRequestInfo) associates a ManagedConnection with the passed in connection. This is a LazyAssociatableConnectionManager extension of IronJacamar.

dissociateManagedConnection(Object, ManagedConnection, ManagedConnectionFactory) dissociates a connection with its ManagedConnection instance. This is a LazyAssociatableConnectionManager extension of IronJacamar.

shutdown shuts down the connection manager, and its related pool instance.

NoTxConnectionManagerImpl provides the implementation for a connection manager configured with NoTransaction.

createConnectionListener(ManagedConnection, ManagedConnectionPool) creates a NoTxConnectionListener and associates it with the ManagedConnection instance.

TxConnectionManagerImpl provides the implementation for a connection manager configured with LocalTransaction or XATransaction.

createConnectionListener(ManagedConnection, ManagedConnectionPool) creates a TxConnectionListener and associates it with the ManagedConnection instance. In case of LocalTransaction a XAResource is created to wrap the local transaction methods of the resource adapter. In case of XATransaction the underlying XAResource instance is wrapped with product information, if configured.

getManagedConnection(Subject, ConnectionRequestInfo) verifies that a valid transaction exists before creating a ManagedConnection, since there is no point in spending resources on work that is going to be rolled back. ironjacamar.allow_marked_for_rollback overrides this behavior.

managedConnectionReconnected(ConnectionListener) enlist the ConnectionListener in the transaction.

managedConnectionDisconnected(ConnectionListener) delist the ConnectionListener from the transaction.

lazyEnlist(ManagedConnection) handles lazy enlistment scenarios as defined by LazyEnlistableConnectionManager.

AbstractConnectionListener provides the methods that are shared across both implementations, NoTxConnectionListener and TxConnectionListener. This base class keeps track off the connection handles used for the associated ManagedConnection.

connectionErrorOccurred(ConnectionEvent) logs the application error, and flushes either the Pool or ManagedConnectionPool depending on the strategy configured.

controls(ManagedConnection, Object) checks if the ManagedConnection and optional connection is controlled by this connection listener.

compareTo(Object) is used to sort the connection listeners based on their last used time.

NoTxConnectionListener is the listener for NoTransaction scenarios.

connectionClosed(ConnectionEvent) dissociates the connection handles, and if there are no handles associated anymore the ManagedConnection is returned to the pool.

TxConnectionListener is the listener for LocalTransaction and XATransaction scenarios.

used() updates the last used time, and resets the timeout value for the underlying XAResource if in XATransaction mode.

enlist() enlists the XAResource instances in the transaction through TransactionSynchronization including resources picked up by the CachedConnectionManager.

delist() delists the XAResource from the transaction in interleaved scenarios.

dissociate() dissociates the ConnectionListener with the transaction.

connectionClosed(ConnectionEvent) dissociates a connection handle through wasFreed(Object) and returns the ManagedConnection in interleaved scenarios.

connectionErrorOccurred(ConnectionEvent) clears any TransactionSynchronization object such that the ManagedConnection can be returned for destruction.

tidyup() will rollback any left over LocalTransaction instance.

isManagedConnectionFree() checks if there is exists a TransactionSynchronization object in track by transaction scenarios, since the ManagedConnection can't be returned in that case.

wasFreed(Object) dissociates a connection handle from the ConnectionListener, or resets the track by transaction flag if null such that the ManagedConnection can be returned.

The TransactionSynchronization class takes care of enlisting the XAResource in the transaction, in track by transaction scenarios. This is done in its enlist() and its result can be verified in checkEnlisted(). The beforeCompletion() method delists the XAResource from the transaction. The afterCompletion(int) method returns the ManagedConnection to the pool.