Sun Microsystems Inc

Connection and Transaction Management Contracts between the Persistence Manager and the ContainerEnterprise JavaBeans 2.0,

•The Persistence Manager calls the getConnection method on the resource manager connection factory that provides connections that have not been enlisted in the current transaction context to obtain a connection that has been not been enlisted in any transaction context. Such a connection is a local connection, rather than an XA connection, so that the persistence manager can manage transactions on the connection using the resource-adaptor-specific API. Persistence managers that use an optimistic concurrency control strategy are expected to make use of such non-enlisted connections for that portion of the transaction that precedes the commit phase. The transaction management on this connection is the responsibility of the persistence manager.

The container is responsible for providing the implementations of the resource manager connection factory methods that the persistence manager uses, and for making the resource manager connection factories for these methods available to the persistence manager through JNDI.

The persistence manager should assume that the container is doing pooling of connections. The persistence manager should therefore hold a connection no longer than necessary.

9.11.3 Connection management scenarios

There are a variety of connection management strategies that the Persistence Manager might use. The following scenarios are intended to be illustrative rather than prescriptive.

9.11.3.1 Scenario: Pessimistic concurrency control

If a persistence manager method (e.g., accessor method, ejbStore() method, etc.) is executing in a distributed (JTA) transaction, the connection that is used to access the database on behalf of that method must run under that same distributed transaction. The Persistence Manager requests the Container to provide a connection that runs in the current transaction context, and caches the connection for use with that transaction.

9.11.3.2 Scenario: Optimistic concurrency control

In general, with an optimistic concurrency control caching strategy, the Persistence Manager needs to be able to use separate connections for the pre-commit phase of the transaction (i.e., the portion of the transaction that precedes the invocation of the Synchronization.beforeCompletion() method) and for the commit phase of the transaction, in order to avoid holding long-term read locks on data if the distributed transaction is running at a high degree of isolation. During the transaction commit phase, the Persistence Manager needs to use a connection that has been enlisted in the distributed transaction context.

The persistence manager obtains a local connection (or a connection that has not been been enlisted in the distributed transaction) for use during the pre-commit phase of the transaction, by calling the getConnection method on the resource manager connection factory that provides connections that have not been enlisted in the current transaction context.

Sun Microsystems Inc.

Entity Bean Component Contract for Container Managed PersistenceEnterprise JavaBeans 2.0, Public Draft Connection and Transac-

When the persistence manager enters the commit phase of the transaction, the persistence manager obtains a connection that has been enlisted in the distributed transaction context of the calling thread by invoking the getConnection method on the resource manager connection factory that provides container management of the transactional enlistment of connections.

9.11.4 Synchronization notifications

If an optimistic concurrency control cache management strategy is used by the Persistence Manager, the Persistence Manager typically needs to be notified when it is necessary to flush its cached state to the database or other persistent store prior to a transaction commit. In order to do so, the Persistence Manager registers a javax.transaction.Synchronization object with the container by using the javax.transaction.Transaction.registerSynchronization() method.

If a synchronization object has been registered, the container will invoke the Synchronization.beforeCompletion() method prior to the start of the transaction completion process. This method executes in the same transaction context as the business method on behalf of which the commit is being executed. The Persistence Manager should use this notification to validate the cached persistent state of the transaction’s entity beans and their associated dependent objects against the database state. If the respective states are not consistent, the Persistence Manager should mark the transaction for rollback using the Transaction.setRollbackOnly() method on the transaction object for the transaction. If the states are consistent, the Persistence Manager must flush the persistent state of the entity beans to the database or other persistent store and close the connections that it is using for the given transaction context.

The Synchronization.afterCompletion() method will be invoked by the container after the transaction is committed or rolled back. The status argument of the afterCompletion() method indicates the outcome of the transaction. The Persistence Manager can use this method to perform cleanup tasks or other management of its cached state.

9.11.5 Container responsibilities

The Container must provide an implementation of the javax.transaction.TransactionManager interface for use by the persistence manager. The Container must make the TransactionManager interface available to the persistence manager in the JNDI name space as java:pm/TransactionManager.

The container must insure that if the local transaction optimization is being used that the getTransaction() method returns a valid (non-null) transaction object that the Persistence Manager can use to identify the transaction context that is in effect.

The container is responsible for making the resource manager connection factories (e.g., javax.sql.DataSource) available to the persistence manager in the persistence manager’s JNDI context.