Overview

Inbound and outbound connections in Geronimo are managed through the J2CA connector framework. This covers JDBC, JMS, DataSources, EIS connectivity, and connection pools. JDBC connectivity is implemented by wrapping JDBC XADataSource, ConnectionPoolDataSource, DataSource, or Driver implementations in J2CA connector wrappers. The wrappers we use are from the codehaus Tranql project.

Transaction Manager

Applications can delegate transaction management to the server infrastructure through application managed UserTransactions or for ejbs container manager transactions. The server uses a transaction manager to coordinate this application view of transaction boundaries with the resource manager view of work done on specific data stores within particular transactions. Geronimo uses a JTA TransactionManager implementation that is extended in three ways:

1. Transaction inflow as required by the J2CA inbound connector requirements
2. Pluggable transaction logging, by default using HOWL (High speed ObjectWeb Logger) for recoverable transaction managers in a server and a non-logging "logger" in application clients
3. Incremental recovery of in doubt transactions as connectors start up after a failure. This allows transactions that use a subset of the deployed connectors to be recovered completely as soon as the connectors they use are restarted, even if some other resource managers are not yet available.

   Requirements for XAResource implementations to enable recovery

   The XA spec does not provide any way to identify which XAResource an xid in an in-doubt transaction is associated with. In order for recovery to work without this information there needs to be a global registry of all resource managers, and recovery can only start after all resource managers are started and connected to the transaction manager. In order to avoid the need for this kind of permanent registry and reliance on the complete environment being present, geronimo associates each xid with the XAResource it is used with. This is done by requiring every XAResource to have a name, by implementing NamedXAResource (a geronimo interface). Also, each connector (or other "source" of an XAResource) is required to register the NamedXAResource with the transaction manager when it starts. The name is stored with the xid, so recovery of a particular transaction can complete as soon as all the XAResources used in that particular transaction have registered.
   The name supplied by a NamedXAResource must be stable over restarts and unique to the resource manager. In geronimo we use the gbean name of the ManagedConnectionFactoryWrapper for outbound connections and the ResourceAdapter gbean name for inbound connectors.

   Configuring the identity of the transaction manager.

   If you are running more than one geronimo instance against a resource manager such as an XADatabase, you need to make sure that the resource manager can distinguish which geronimo instance is making each request. You do this by setting the transaction manager identity. See Configuring+the+Transaction+Manager+Identity

Connector Framework

The J2CA connector spec provides a reasonable approach to configuring and pooling outbound connections and configuring and managing inbound message delivery. Geronimo uses this for jdbc connection support by wrapping jdbc artifacts in the required J2CA artifacts, using the tranql project wrappers.

Connection Pooling (outbound connectors)

Often connections to legacy EIS systems and databases have connections that are extremely expensive to set up. Rather than creating a new connection to the external system every time one is needed, normally you use a connection pool: when a connection is needed an unused connection is supplied from the pool, and when the application is done with it the connection is put back in the pool. The J2CA spec supports this idea with these components:

Connection Factory

A connection factory (e.g. DataSource) is a component used by an application to get "connections" it can use. These connections are short lived, lightweight handles or wrappers to underlying "physical" managed connections. When an application calls datasource.getConnection(), the connection factory routes the request to the connection manager, which supplies a suitable connection handle from a cached, pooled, or new connection.

ConnectionManager

The connection manager received connection requests from the connection factory and figures out how to accomodate them. It also receives notification of transaction events and transfer of control between application components such as ejbs.
Generally, if there is a cached ManagedConnection in the environment, the connection manager returns a new handle to the cached ManagedConnection. Otherwise it looks for a suitable ManagedConnection in the pool, and returns a handle to such a connection if it exists. Otherwise it creates a new connection.

Transaction support

Connection managers in geronimo can be configured with xa, local, or no transaction support.

No transaction

No Transaction support means that connections are never enrolled in jta transactions and committing such a jta transaction has no effect on any connections managed by the connection manager. In this case the connection manager does no caching and each connection request is handled independently.

Local transaction

Local transaction support relies on the connector support of j2ca local transaction control. This maps to such things as non-xa jdbc Driver, DataSource, and ConnectionPoolDataSource implementations. In this case geronimo constructs a "fake" XAResource that enables the JTA transaction manager to control the local transaction, however xa features such as separation of prepare and commit phases and recovery are not implemented. Since the resource manager has no transaction identifier that lets it distinguish which transaction work is being done on, the connection manager has to keep track of this by caching all the connections enrolled in a jta transaction. Whenever your application requests a connection while in a jta transaction, the connection manager checks for an existing connection enrolled in this transaction and if found supplies an additional handle to it. If no connection is associated, one is fetched from the pool (or created anew) and cached with the transaction. Furthermore, closing one or all of these connection handles will not result in returning the connection to the pool. The connection is returned to the pool only when all the handles have been closed and the jta transaction completes.

XA transaction

XA transaction support should theoretically not require caching connections with transactions but in practice usually does. The XA spec indicates that any connection should be able to handle work in any transaction at any time, but few if any XA capable resource managers actually implement this. Normally you must do all work in a JTA transaction against a given resource manager over the same physical connection. Setting transaction-caching on will assure that this caching takes place.
The intent of the enlist/delist methods on XAResource appears to be to support reusing a connection in a thread as it enters and leaves "Requires New" transaction boundaries. By default geronimo does not attempt to reuse connections in this way: the connections associated with the previous transaction are left associated with it and new connection requests get new ManagedConnections from the pool. There is an experimental configuration to reuse the connections already associated with the thread.