TechFAQ

One of the key features of the Enterprise JavaBeans architecture is support for distributed transactions. The Enterprise JavaBeans architecture allows an application developer to write an application that atomically updates data in multiple databases which may be distributed across multiple sites. The sites may use EJB Servers from different vendors.

The Bean Provider can choose between using programmatic transaction demarcation in the enterprise bean code (this style is called bean-managed transaction demarcation) or declarative transaction demarcation performed automatically by the EJB Container (this style is called container-managed transaction demarcation).

With bean-managed transaction (BMT) demarcation, the enterprise bean code demarcates transactions using the javax.transaction.UserTransaction interface. All resource manager accesses between the UserTransaction.begin() and UserTransaction.commit() calls are part of a transaction.

package javax.transaction;

public interface UserTransaction {
	public void begin() throws 
		NotSupportedException,
		SystemException;
	public void commit() throws 
		RollbackException,
		HeuristicMixedException,
		HeuristicRollbackException,
		SecurityException,
		IllegalStateException,
		SystemException;
	public void rollback() throws 
		IllegalStateException,
		SecurityException,
		SystemException;
	public void setRollbackOnly() throws
		IllegalStateException,
		SystemException;
	public int getStatus() throws 
		SystemException;
	public void setTransactionTimeout (int seconds) throws
		SystemException;
}
					

The terms "resource" and "resource manager" refer to the resources declared in the enterprise bean's deployment descriptor using the resource-ref element. This includes not only database resources, but also JMS Connections. These resources are considered to be "managed" by the Container.

With container-managed transaction (CMT) demarcation, the Container demarcates transactions per instructions provided by the Application Assembler in the deployment descriptor. These instructions, called transaction attributes, tell the container whether it should include the work performed by an enterprise bean method in a client's transaction, run the enterprise bean method in a new transaction started by the Container, or run the method with "no transaction".

The Enterprise JavaBeans architecture supports FLAT transactions. A flat transaction cannot have any child (nested) transactions.

The EJB architecture DOES NOT require the EJB Container to support the JTS interfaces. The EJB architecture REQUIRES that the EJB Container support the JTA API.

When designing an enterprise bean, the Bean Provider MUST decide whether the enterprise bean will demarcate transactions programmatically in the business methods (bean-managed transaction demarcation), or whether the transaction demarcation is to be performed by the Container based on the transaction attributes in the deployment descriptor (container-managed transaction demarcation).

A Session Bean or a Message-driven Bean can be designed with bean-managed transaction (BMT) demarcation OR with container-managed transaction (CMT) demarcation. (But it CANNOT be both at the same time.)

An Entity Bean MUST ALWAYS be designed with container-managed transaction (CMT) demarcation.

An enterprise bean instance can access resource managers in a transaction ONLY in the enterprise bean's methods in which there is a TRANSACTION CONTEXT available. An entity bean with container-managed persistence can access its persistent state in a transaction ONLY in the enterprise bean's methods in which there is a TRANSACTION CONTEXT available.

Some enterprise beans may need to access resource managers that do not support an external transaction coordinator. The Container cannot manage the transactions for such enterprise beans in the same way that it can for the enterprise beans that access resource managers that support an external transaction coordinator.

If an enterprise bean needs to access a resource manager that does not support an external transaction coordinator, the Bean Provider should design the enterprise bean with container-managed transaction demarcation and assign the NotSupported transaction attribute to all the bean's methods. The EJB architecture does not specify the transactional semantics of the enterprise bean methods.

Requirements for the Bean Provider of an enterprise bean with bean-managed transaction (BMT) demarcation.

The enterprise bean with bean-managed transaction demarcation MUST be a Session bean or a Message-driven bean (NOT Entity bean).

<ejb-jar>
	<enterprise-beans>    
		<session>    
			<ejb-name>CompanySearch</ejb-name>
			<home>com.ejb.CompanySearchHome</home>
			<remote>com.ejb.CompanySearch</remote>
			<ejb-class>com.ejb.CompanySearchEJB</ejb-class>
			<session-type>Stateless</session-type>
			<transaction-type>Bean</transaction-type>
			<resource-ref>
				<res-ref-name>jdbc/mydb</res-ref-name>
				<res-type>javax.sql.DataSource</res-type>
				<res-auth>Container</res-auth>
			</resource-ref>
		</session>
		...
	</enterprise-beans>    
	...
</ejb-jar>  

					

NOTE, Entity beans declarations DO NOT have transaction-type element, since all of them use CMT ONLY.

An instance that starts a transaction must complete the transaction before it starts a new transaction.

The Bean Provider uses the UserTransaction interface to demarcate transactions. All updates to the resource managers between the UserTransaction.begin() and UserTransaction.commit() methods are performed in a transaction. While an instance is in a transaction, the instance MUST NOT attempt to use the resource-manager specific transaction demarcation API (e.g. it MUST NOT invoke the commit() or rollback() method on the java.sql.Connection interface or on the javax.jms.Session interface).

A STATEFUL Session Bean instance may, but is not required to, commit a started transaction before a business method returns. If a transaction has not been completed by the end of a business method, the Container retains the association between the transaction and the instance across multiple client calls until the instance eventually completes the transaction.

A STATELESS session bean instance MUST COMMIT a transaction before a business method returns.

A message-driven bean instance MUST COMMIT a transaction before the onMessage method returns.

An enterprise bean with bean-managed transaction demarcation MUST NOT use the getRollbackOnly() and setRollbackOnly() methods of the EJBContext interface.

An enterprise bean with bean-managed transaction demarcation has no need to use these methods, because of the following reasons:

NOTE, that method setRollbackOnly() exists in BOTH interfaces javax.transaction.UserTransaction AND javax.ejb.EJBContext.

The following code illustrates the use of JTA interface to specify transactions in an enterprise bean with bean-managed transaction demarcation:

UserTransaction ut = ejbContext.getUserTransaction();
ut.begin();
// Transactional work is done here
ut.commit();
					

or

Context ctx = new InitialContext();
UserTransaction ut = (UserTransaction)ctx.lookup("java:comp/UserTransaction");
try {
	ut.begin();
	//Do some work...
	ut.commit();
}
	catch(Exception e) {
	ut.rollback();
}
					

NOTE, javax:comp/UserTransaction is a standard JNDI name used to look up a user transaction object in a J2EE container. The begin() and commit() method calls can be in SEPARATE methods (only for STATEFUL session beans). Just perform an additional lookup in your new method to obtain a handle on the SAME javax.transaction.UserTransaction object associated with this session.

Requirements for the Bean Provider of an enterprise bean with container-managed transaction (CMT) demarcation.

The enterprise bean's business methods or onMessage(...) method MUST NOT use any resource-manager specific transaction management methods that would interfere with the Container's demarcation of transaction boundaries. For example, the enterprise bean methods must not use the following methods of the java.sql.Connection interface: commit(), setAutoCommit(...), and rollback() or the following methods of the javax.jms.Session interface: commit() and rollback().

The enterprise bean's business methods or onMessage(...) method must not attempt to obtain or use the javax.transaction.UserTransaction interface.

A STATEFUL Session Bean with container-managed transaction demarcation can optionally implement the javax.ejb.SessionSynchronization interface.

An enterprise bean with container-managed transaction demarcation can use the setRollbackOnly() method of its EJBContext object to mark the transaction such that the transaction can never commit. Typically, an enterprise bean marks a transaction for rollback to protect data integrity before throwing an application exception, because APPLICATION exceptions DO NOT automatically cause the Container to rollback the transaction.

An enterprise bean with container-managed transaction demarcation can use the getRollbackOnly() method of its EJBContext object to test if the current transaction has been marked for rollback. The transaction might have been marked for rollback by the enterprise bean itself, by other enterprise beans, or by other components (outside of the EJB specification scope) of the transaction processing infrastructure.