Configuring transactions in the Eclipse Amlen resource adapter

You can use the following information to understand transaction options for Enterprise JavaBeans™ (EJBs), message handling options in Eclipse Amlen for message driven beans (MDBs), and Eclipse Amlen transaction options for J2C connection factories.

Transaction options for EJBs

In an EJB application, there are two basic options for transaction management.

Bean managed transactions

In bean managed transactions, the bean method creates transactions with the UserTransaction interface. The transactions are created when they are needed.
Container managed transactions

In container managed transactions, the EJB container provides the transaction context for the bean. This type of transaction is the default option.

Container managed transactions can be configured with one of the following transaction attributes:

Required

Directs the container to start the bean method within a transaction context. If a client calls a bean method from within a transaction context, the container calls the bean method within the client transaction context. If a client calls a bean method outside a transaction context, the container creates a new transaction context and calls the bean method from within that context. The transaction context is passed to any enterprise bean objects or resources that are used by this bean method.

RequiresNew

Directs the container to always start the bean method within a new transaction context, regardless of whether the client calls the method within or outside a transaction context. The transaction context is passed to any enterprise bean objects or resources that are used by this bean method.

Mandatory

Directs the container to always start the bean method within the transaction context that is associated with the client. If the client attempts to start the bean method without a transaction context, the container generates an exception to the client. The transaction context is passed to any EJB object or resource that is accessed by an enterprise bean method. EJB clients that access these entity beans must do so within an existing transaction. For other enterprise beans, the enterprise bean or bean method must implement the bean managed value or use the Required or RequiresNew value. For non-enterprise bean clients, the client must start a transaction by using the UserTransaction interface.

Supports

Directs the container to start the bean method within a transaction context if the client calls the bean method within a transaction. If the client calls the bean method without a transaction context, the container calls the bean method without a transaction context. The transaction context is passed to any enterprise bean objects or resources that are used by this bean method.

NotSupported

Directs the container to start bean methods without a transaction context. If a client calls a bean method from within a transaction context, the container suspends the association between the transaction and the current thread before starting the method on the enterprise bean instance. The container then resumes the suspended association when the method invocation returns. The suspended transaction context is not passed to any enterprise bean objects or resources that are used by this bean method.

Never

Directs the container to start bean methods without a transaction context. If the client calls a bean method from within a transaction context, the container generates an exception. If the client calls a bean method from outside a transaction context, the container behaves in the same way as if the NotSupported transaction attribute was set. The client must call the method without a transaction context.

For more information about EJB configuration and transaction management, see the Oracle Java™ EE tutorial sections for container or bean managed transactions in the product documentation on the Oracle website.

Eclipse Amlen message handling options for MDBs

You can configure an MDB to run outside a container transaction scope by specifying either bean managed transactions or container managed transactions with the transaction attribute set to NotSupported. The EJB container automatically acknowledges the messages that are processed by the onMessage() method, even if the onMessage() method fails unexpectedly. The mode for acknowledging received messages depends upon the configuration setting for the acknowledgeMode property in the J2C activation specification.

When unexpected failures are due to transient system issues, messages can be lost. To prevent this type of message loss, you can set the enableRollback property to true for the J2C activation specifications in the Eclipse Amlen resource adapter. By default, enableRollback is set to false so all messages are automatically acknowledged. When enableRollback is set to true, a message is rolled back to the topic or queue when the onMessage() method fails. This rollback allows the message to be redelivered and reprocessed.

Setting enableRollback to true is useful for redelivery of messages when transient issues cause the onMessage() method to fail. However, setting enableRollback to true can trigger the redelivery of poison messages. A poison message is a message that a receiving application cannot process. To avoid redelivery of poison messages when you set enableRollback to true, you must ensure that you can handle poison messages in your JMS application. For more information about handling poison messages, see Poison messages.

Eclipse Amlen transaction options for J2C connection factories

J2C connection factories can be used in various types of Java Platform, Enterprise Edition (Java EE) applications.

The transaction scope of a Java EE application depends on the containers that it uses as well as the configuration of the components that it uses. An application server typically coordinates these activities by using global transactions. However, if you want to force the transaction scope, you can do so by setting the transactionSupportLevel property in the Eclipse Amlen resource adapter for connection objects that use Eclipse Amlen J2C connection factories. Changing the default setting for transactionSupportLevel must be done only by someone with expert knowledge about the application. You can set the transactionSupportLevel to one of the following values:

XATransaction

This setting enables the connection factory object to support global or local transactions. The application server sets the appropriate scope. XATransaction is the default setting.
LocalTransaction

If only one resource manager is required for the application, transactionSupportLevel can be set to LocalTransaction. This setting ensures that only local transaction context is used by connections that are configured by this connection factory.
NoTransaction

If no transactions are required for the application, transactionSupportLevel can be set to NoTransaction. This setting turns off transaction processing for connections that are using the connection factory.

These options can be useful in optimizing connection throughput but must be used with caution. For example, serious application failures can occur if the transactionSupportLevel setting for a J2C connection factory conflicts with the transaction configuration of an EJB that uses the connection factory to create a connection.