10.1 Declarative Transaction Demarcation

Most applications are best off using the container-managed transaction demarcation feature, commonly referred to as declarative transaction demarcation, or declarative transactions. For this feature to work, application developers set up transaction attributes separate from their code: A transaction attribute is associated with each enterprise bean method. The EJB container uses these attributes to determine how it should handle transaction demarcation for that method. As a result, the application programmer does not need to include transaction demarcation code in the application.

10.1.1 Transaction Attributes

When a client uses an enterprise bean's home or component interface to invoke a method, the container interposes on the method invocation to inject the container services. One of the services that the container injects is transaction demarcation.

The bean developer or application assembler uses the deployment descriptor to specify how the container should manage transaction demarcation. Essentially, the deployment descriptor allows the bean developer or application assembler to specify a transaction attribute for each method of the component and home interfaces.

Keep in mind that there are some limitations on the methods to which transaction attributes may be assigned. The deployment descriptor may not assign a transaction attribute to some of the methods of the home and component interfaces. For example, a session bean may define a transaction attribute only for the business methods defined in the bean's component interface, not to the methods of the home interface. In addition, a session bean may not assign transaction attributes to the methods defined in the EJBObject or EJBLocalObject interface, because the container implements these methods. Therefore, it is meaningless to define a transaction attribute for them.

Like a session bean, an entity bean may define a transaction attribute for each of the business methods in the bean's component interface. In addition, an entity bean may define transaction attributes for the create, find, and home methods defined in the home interface and for the remove methods inherited from the EJBObject/EJBLocalObject and EJBHome/EJBLocalHome interfaces. However, an entity bean may not define transaction attributes for all other methods defined in the EJBObject/EJBLocalObject and EJBHome/EJBLocalHome interfaces. Because the container implements these other methods, it would be meaningless for the entity bean to define a transaction attribute for them.

It is important to note one implication of this rule. The create and remove methods of an entity bean have transaction attributes, but the create and remove methods of a session bean do not have transaction attributes. The container treats the create and remove methods of a session bean as if they had the NotSupported transaction attribute.

10.1.2 Transaction Attribute Values

A transaction attribute may have one of six values:

1. Required

2. RequiresNew

3. Supports

4. NotSupported

5. Mandatory

6. Never

The following sections explain how transaction attributes are used.

Required

The Required transaction attribute is typically used for the bean methods that update databases or other transaction-capable resource managers and hence is used for the methods of CMP entity beans. The Required transaction attribute ensures that all the updates from the method are performed atomically and that the updates done by the enterprise bean method can be included in a larger transaction. A transaction is required in such scenarios to achieve application correctness.

How does the container interpret and apply the Required transaction attribute? If a method is assigned the Required transaction attribute, the container executes the method with a transaction context so that one of two events occurs:

1. If the method caller is already associated with a transaction context, the container includes the execution of the method in the client's existing transaction context.

2. If the method caller is not associated with a transaction context, the container starts a transaction before the execution of the method and commits the transaction after the method has completed.

The EnrollmentBean in the application in Chapter 8 uses the Required transaction attribute for the commitSelections method. By using this attribute for this method, the application ensures that the updates to BenefitsDatabase and the payroll system are performed as a single transaction.

RequiresNew

The RequiresNew transaction attribute, like the Required attribute, is typically used for methods that update databases. However, methods that use the RequiresNew attribute should have the database updates committed regardless of the outcome of the caller's transaction.

The container applies the RequiresNew transaction attribute somewhat differently than the Required attribute does. The container always executes a method that is assigned the RequiresNew transaction attribute in a new transaction context. This means that the container starts a new transaction before executing the method and commits the transaction after the method completes. If the method caller is already associated with a transaction context when calling the method, the container suspends the association for the duration of the new transaction.

In what situations would the RequiresNew transaction attribute be useful? An application service provider may want to track, for marketing or billing purposes, the applications that each of its users has executed. Use of the RequiresNew attribute enables the application service provider to implement such tracking. The service provider uses the ApplicationStatistics enterprise bean for collecting the application use information. Each time a user invokes an application, it in turn invokes the recordUsage method on the ApplicationStatistics bean. The recordUsage method is assigned the RequiresNew transaction attribute to ensure that it records the use information even if the actual application rolls back its transaction. In contrast, if the Required attribute were used for the recordUsage method and the application rolled back its transaction, there would be no record that the user ran the application.

Supports

The Supports transaction attribute is used when a method does not absolutely require a transaction. When a method is assigned the Supports transaction attribute, the method's transaction context depends on the transaction context of the method caller. The container executes the method with or without a transaction context, depending on whether the method caller is associated with a transaction context.

If the caller is associated with a transaction context, the container includes the method execution in the caller's transaction. (In this case, the container's execution of the method is the same as if the method had been assigned the Required transaction attribute.)

If the caller is not associated with a transaction context, the container executes the method in a manner that transaction semantics are not defined by the EJB specification. (In this case, the container's execution of the method is the same as if the method had been assigned the NotSupported transaction attribute.)

When would you use the Supports transaction attribute? You typically use this attribute for those methods in which atomicity of multiple updates from within the method is not an issue. These cases include methods that make no updates directly or indirectly via other enterprise beans to data. Or, they perform only a single data-update operation that is guaranteed to be atomic by other mechanisms, such as atomicity of an SQL statement. The Supports attribute allows the container to avoid the overhead of using a transaction for executing a method when a transaction is not needed. At the same time, the attribute tells the container to include the work of the method into the client's transaction when this is required.

NotSupported

A method may also be assigned the NotSupported transaction attribute. In this situation, the container invokes the method in a manner that transaction semantics are not defined by the EJB specification. Normally, the EJB specification allows the container to invoke a method with no transaction context or in some container-specific local transaction context. When a caller invokes a method with the NotSupported transaction attribute and the caller is associated with a transaction context defined by the EJB specification, the container suspends the caller's transaction association for the duration of the method.

When would you use the NotSupported transaction attribute? You typically use the NotSupported transaction attribute in two cases. You would assign this attribute to those methods of an enterprise bean that use resource managers not capable of interfacing with an external transaction coordinator or when the correct application semantics do not depend on performing resource manager access in a transaction.

When an enterprise bean uses resource managers incapable of interfacing with an external transaction coordinator, the container cannot propagate the transaction context into the resource managers. Using the NotSupported transaction attribute for the bean's methods instructs the container that the application developer has taken into consideration the dependency on the less capable transaction manager.

The example application in Chapter 9, Using Enterprise JavaBeans in Web Services, uses the NotSupported attribute for the methods of the WrapperPlanBean enterprise bean. WrapperPlanBean uses the Providence Health Web service. Because Web services do not support propagating a transaction, the assembler or bean developer assigned the NotSupported transaction attribute to all the methods of the WrapperPlanBean enterprise bean. The bean developer designed the WrapperPlanBean such that its communication with Providence Health's Web service does not require a transaction for its correctness.

Mandatory

When a method is assigned the Mandatory transaction attribute, the container first checks that the caller is associated with a transaction context. If the caller is not associated with a transaction context, the container throws the javax.transaction.TransactionRequired exception to the caller. If the client is associated with a transaction, the container performs the method invocation in the same way as for the Required attribute: The container includes the execution of the method in the client's existing transaction context.

When would you use the Mandatory transaction attribute? Use this attribute for a method for which an application assembly error would occur if the method were invoked by a caller without a transaction context.

Never

When a method is assigned the Never transaction attribute, the container first checks that the caller is associated with a transaction context. If the caller is associated with a transaction context, the container throws java.rmi.RemoteException to the client. If the caller is not associated with a transaction, the container invokes the method in the same way as the NotSupported attribute. You use the Never attribute when you want the container to ensure that a transactional client does not invoke an enterprise bean method that is not capable of transaction.

Summary of Transaction Attributes

Table 10.1 summarizes the transaction context that the EJB container passes to an invoked business method. The table also illustrates the transaction context that the container passes to the resource managers called by the invoked business method. As illustrated, the transaction context passed by the container is a function of the transaction attribute and the client's transaction context.

In Table 10.1, T1 represents a transaction passed with the client request; T2 represents a transaction initiated by the container. Keep in mind that the enterprise bean's business method may invoke other enterprise beans via their home and component interfaces. When this occurs, the transaction indicated beneath the column Transaction Associated with Business Method is passed as part of the client context to the target enterprise bean.

Table 10.1. Summary of Transaction Attributes

Transaction Attribute	Client's Transaction	Transaction Associated with Business Method	Transaction Associated with Resource Managers
Required	None T1	T2 T1	T2 T1
RequiresNew	None T1	T2 T2	T2 T2
Supports	None T1	None T1	None T1
NotSupported	None T1	None None	None None
Mandatory	None T1	Error T1	NA T1
Never	None T1	None Error	None NA

Note on Transaction Attributes for Entity Beans

As explained in Section 7.2.4, Caching Entity Bean State, on page 219, a BMP entity bean may use the ejbLoad and ejbStore methods to perform caching of data. For this caching to work correctly, the container must combine the ejbLoad method, the business methods, and the ejbStore method into a single transaction. This means that if the bean depends on the ejbLoad and ejbStore methods to manage caching, it should not be using the NotSupported, Supports, and Never transaction attributes.

10.1.3 Transaction Attributes for Message-Driven Beans

Message-driven beans have only one method, onMessage, to which the container delivers messages. Because transaction context never flows over JMS messages, a message-driven bean can never perform work in the scope of the client's transaction. The transaction attributes of the onMessage method are hence restricted to Required and NotSupported.

If the onMessage method has a transaction attribute of Required, the container starts a transaction before invoking the method, and all work done by onMessage such as database access, invocations on other beans, and so forth are part of that new transaction. In addition, the message delivery itself is part of the transaction. This means that if the transaction aborts for any reason, such as a failed database update attempt by the bean, the message delivery is also aborted. The Required transaction attribute also ensures that the container redelivers the message at a later point.

If the onMessage method has the NotSupported transaction attribute, the container does not start a transaction before calling the message-driven bean. In other words, the message-driven bean runs without a transaction.

Message-driven beans may also use bean-managed transaction demarcation, as described in Section 10.2.2, Transaction Demarcation by a Session Bean, on page 338.

10.1.4 Transaction Attributes for Sample Application

Table 10.2 shows the transaction attributes used for methods of the entity bean sample application the application discussed in Chapter 7, Understanding Entity Beans, and Chapter 9, Using Enterprise JavaBeans in Web Services. Following the table is an explanation of why these attributes were assigned in this manner.

Table 10.2. Method Transaction Attributes for Sample Application

Enterprise Bean Name	Method Name	Transaction Attribute
Enrollment	getEmployeeInfo, getCoverageOptions, setCoverageOption, getMedicalOptions, setMedicalOption, getDentalOptions, setDentalOption, isSmoker, setSmoker, getSummary	Supports
	commitSelections	Required
Selection	getCopy, updateFromCopy, remove	Required
SelectionHome	create, findByPrimaryKey, remove	Required
Plan	getPlanType, getPlanId, getPlanName, getAgeFactor, setAgeFactor, getCoverageFactor, setCoverageFactor, getSmokerCost, setSmokerCost, addDoctor, removeDoctor, getCost, getAllDoctors, getDoctorsByName, getDoctorsBySpecialty, remove	Required
PlanHome	create, findByPrimaryKey, findMedicalPlans, findDentalPlans, findByDoctor, updateSmokerCosts, getMedicalPlanNames, getDentalPlanNames, remove	Required
Doctor	getFirstName, getLastName, getSpecialty, getHospitals, getPracticeSince, remove	Required
DoctorHome	create, findByPrimaryKey, remove	Required
Employee	getEmployeeNumber, getFirstName, getLastName, getBirthDate, remove	Required
EmployeeHome	create, findByPrimaryKey, remove	Required
Payroll, PayrollLocal	setSalary, getSalary, setBenefitsDeduction, getBenefitsDeduction	Supports
PayrollMDB	onMessage	Required
InsurancePlanAdmin	createInsurancePlan, getPlanInfo, addDoctors, removeDoctors, getAllDoctors, setSmokerCost, setAgeFactor, setCoverageFactor	Required
WrapperPlanEJB	all methods	NotSupported
WrapperDoctorEJB	all methods	NotSupported

Wombat assigned the Required transaction attribute to the commitSelections method defined in the Enrollment remote interface. The commitSelections method updates multiple databases, and therefore Wombat uses a transaction to achieve atomicity of the multiple updates. Wombat assigned the Supports attribute to all other methods of the Enrollment remote interface because these methods do not require a transaction for their correctness. (The methods only read data from the database.)

Wombat assigned the Required transaction attribute to all the methods of all the entity beans. Using the Required attribute is typical for methods of an entity bean because it guarantees that the container includes the execution of the ejbLoad method, the business methods, and the ejbStore method in a single transaction. See Section 7.2.4, Caching Entity Bean State, on page 219.

Star Enterprise assigned the Supports transaction attribute to the methods on the PayrollEJB's local and remote interfaces. The Supports transaction attribute allows the work performed by those methods to be part of the client's transaction, if there is one. However, if there is no client transaction, the work performed by PayrollEJB is not part of a global transaction. Star Enterprise also assigned the Required attribute to the onMessage method of the PayrollMDB message-driven bean because the work it performs, as well as the message delivery, needs to be part of the same transaction. If the payroll update is aborted for any reason, the message delivery also needs to be aborted, and the message needs to be redelivered.

The InsurancePlanAdmin Web service interface has all its methods set to the Required attribute. This allows InsurancePlanAdmin to make multiple fine-grained calls on the PlanEJB and DoctorEJB entity beans through their local interfaces within the scope of one transaction. If InsurancePlanAdmin did not run in a transaction, each call on PlanEJB and DoctorEJB would result in a separate transaction starting and committing, and this would greatly increase performance overhead.

The WrapperPlanEJB and WrapperDoctorEJB beans have all their methods set to the NotSupported transaction attribute. They do this because they do not perform any transactional work by themselves. Instead, they delegate all transactional work to the Providence Health Web service.