The target audience for this guide is the Enterprise Bean provider, i.e. the person in charge of developing the software components on the server side. It explains how to define the transactional behaviour of an EJB application.
The content of this guide is the following:
In case of container-managed transaction management, the transactional behaviour of an enterprise bean is defined at configuration time, and is part of the assembly-descriptor element of the standard deployment descriptor. It is possible to define a common behaviour for all the methods of the bean, or to define it at the method level. It is achieved by specifying a transactional attribute, which can be one of the following:
Transaction Attribute | Client transaction | Transaction associated with enterprise Bean's method |
NotSupported | -
T1 |
-
- |
Required | -
T1 |
T2
T1 |
RequiresNew | -
T1 |
T2
T2 |
Mandatory | -
T1 |
error
T1 |
Supports | -
T1 |
-
T1 |
Never | -
T1 |
-
error |
In the deployment descriptor, the specification of the transactional attributes appears in the assembly-descriptor as follows:
<assembly-descriptor> <container-transaction> <method> <ejb-name>AccountImpl</ejb-name> <method-name>*</method-name> </method> <trans-attribute>Supports</trans-attribute> </container-transaction> <container-transaction> <method> <ejb-name>AccountImpl</ejb-name> <method-name>getBalance</method-name> </method> <trans-attribute>Required</trans-attribute> </container-transaction> <container-transaction> <method> <ejb-name>AccountImpl</ejb-name> <method-name>setBalance</method-name> </method> <trans-attribute>Mandatory</trans-attribute> </container-transaction> </assembly-descriptor>
In this example, for all methods of the AccountImpl bean which are not explicitly specified in a container-transaction element, the default transactional attribute is Supports (defined at the bean-level), and for the methods getBalance and setBalance their respective transactional attributes are Required and Mandatory (defined at the method-name level).
A bean that manages its transactions itself must set the transaction-type element in its standard deployment descriptor to:
<transaction-type>Bean</transaction-type>
To demarcate the transaction boundaries in a bean with bean-managed transactions, the bean programmer should use the javax.transaction.UserTransaction interface, defined on an EJB server object that may be obtained using the EJBContext.getUserTransaction() method (the SessionContext object or the EntityContext object depending if the method is defined on a session or an entity bean). The example below shows a session bean method "doTxJob" demarcating the transaction boundaries; the UserTransaction object is obtained from the sessionContext object, that should have been initialized in the setSessionContext method (see the example of the session bean).
public void doTxJob() throws RemoteException { UserTransaction ut = sessionContext.getUserTransaction(); ut.begin(); ... // transactional operations ut.commit(); }
Another way to do this is to use JNDI and to retrieve UserTransaction with the name java:comp/UserTransaction in the initial context.
As explained in the previous section, the transactional behaviour of an application can be defined in a declarative way, or coded in the bean and/or the client itself (transaction boundaries demarcation). In any case, the distribution aspects of the transactions are completely transparent to the bean provider and to the application assembler. This means that a transaction may involve beans located on several EJB servers and that the platform will take in charge the management of the global transaction by itself. It will perform the two phase commit protocol between the different servers and the bean programmer will have nothing to do for this purpose.
Once the beans have been developed and the application has been assembled, it is possible for the deployer and for the administrator to configure the distribution of the different beans on one or several machines, and within one or several EJB servers. This may be done without impacting neither the beans code nor their deployment descriptors. The distributed configuration is specified at launch time: in the environment properties of an EJB server, you may specify
To achieve this goal, two properties must be set in your jonas.properties file, jonas.service.ejb.descriptors and jonas.service.jtm.remote. The first one lists the beans that will be handled on this EJB server (by specifying the name of their deployment descriptors files or the name of the ejb-jar files), and the second one sets the Java Transaction Monitor (JTM) launching mode:
Example:
jonas.service.ejb.descriptors Bean1.xml, Bean2.xml jonas.service.jtm.remote false
The Java Transaction Monitor may run outside of any EJB server, in this case, it may be launched in a stand alone way using the following command:
TMServer
Using this configuration facilities, it is possible to adapt the beans distribution to the resources (cpu and data) location, so that performance may be optimal.
The figure below illustrates four cases of distribution configuration of three beans.
These different configuration cases may be obtained by launching the EJB servers and eventually the JTM (case 3) with the adequate properties. The rational when opting for one of these configurations is resources location and load balancing. However, the following hints may be noted: