How-To Setup Mid-tier Two Phase Commit Coordinator for
EJB transactions
Date: 22/12/2003
After
completing this HowTo you should be able to:
•
Understand the two-phase commit protocol
• Setup mid-tier two-phase commit coordinator in OC4J 10.0.3
• Test an EJB application that uses two-phase commit
One of the important features of the J2EE architecture
is the support for transactions. Enterprise applications quite often require
access to data from different datasources. These application components
acquire multiple connections to multiple resource managers. An additional
requirement may be to access multiple databases within a single transaction.
It is possible to implement this feature only if the underlying application
server supports access to multiple JDBC databases in one transaction using
the Two-Phase Commit protocol.
This How-to takes a sample application which contains
Enterprise Java Bean (EJB) components and explains how to configure the
transaction manager of OC4J to perform logging in order to recover any in-doubt
transactions in case of failure. This is required to ensure the ACID properties
of a transaction that scopes work done on multiple resource managers. This
example does not intend to demonstrate failure and recovery of transactions.
Prerequisites
To work your way through this HowTO, you will need to have
an understanding of OC4J transaction manager and the datasource requirement
to achieve Two Phase Commit. The function of Transaction manager is to co-ordinate
distributed/global transaction. The transaction manager is responsible for
making the final decision either to commit or rollback any distributed transaction.
A commit decision should lead to a successful transaction; rollback leaves
the data in the database unaltered.
Oracle9i
database (version 9.0.1 or later): (Assuming one or both databases
are Oracle) OE Schema that is part of Oracle9i
Sample Schemas will be required. Refer here
for details on installing the OE schema if its not existing
in your Oracle9i database.
Note : If you are
using an Oracle8i
database, please execute the OE
schema creation scripts in the Oracle8i database to install the sample
schema. If other third party databases are used, make sure the tables
ORDERS, ORDER_ITEMS, PRODUCT_INFORMATION are created as required by the
entities of this application.
HowTo Setup Mid-tier Two Phase Commit
for EJB transactions
This application demonstrates Two Phase Commit with EJB
transactions using two Oracle databases by considering the following scenario.
This application is a web-based application simulating a simple Order Entry
System with Java Server Pages (JSPs) at the frontend. The JSPs are used to
Add a new Order Item or Delete an Order Item from both the databases. Entity
Beans with Container-Managed Persistence (CMP) are created based on database
tables (from OE Schema) in two different databases. The Entity
Beans are in turn accessed by a Stateless Session Bean which has Bean-Managed
transactions meaning that the JTA transaction logic will be coded within
the Session Bean. The JSPs pass on the request to the Stateless Session Bean
which has methods to create new Entity objects and/or delete existing entity
objects in both the databases within a single transaction with the help of
the CMP Entity Beans.
Here, the Entity Beans are created based
on the Order Entry tables from the OE sample schema. The application
flow is as follows :
The Main JSP allows the user to enter
values to add a new order item. The request is passed on to the insertOrderItem()
method of the Session Bean which Creates a new Order Item record in both
the databases, Retrieves the product price details and Updates the Total
value of the Order in both the databases. The Inserts and Updates are part
of a single transaction and the transaction is marked to make sure that
either all are committed or rolledback.
The Delete JSP deletes the order
item. The request is passed on to the deleteOrderItem() method of the Session
Bean which Deletes the Order Item record in both the databases, Retrieves
the product price details and Updates the Total value of the Order in both
the databases. The Deletes and Updates are part of a single transaction
and the transaction is marked to make sure that either all are committed
or rolledback.
Following are the steps involved
in implementing the application to demonstrate the Two Phase Commit :
Extract the file ejb2pc.zip using unzip/winzip utility.
This will create directory 'ejb2pc' which contains all the documentation
and source code for this how-to.
Step 2. Configure the Transaction
Manager
As specified in Prerequisites, ensure that the OC4J Transaction
Manager is configured in server.xml and the log file location is specified
correctly in transaction-manager.xml.
<log type="multi-file" location="d:\translogs"/>
Start the OC4J server with native CMP as follows :
> java -jar oc4j.jar
Step 3. Configure the datasources
As specified in Prerequisites, configure the XA-compliant
datasources. For the example application, the data-sources are pre-configured
to use two Oracle databases in the file ejb2pc\src\META-INF\data-sources.xml.
Change the attributes according to your database setup in data-sources.xml.
If two Oracle databases are used, change the 'url' attribute in data-sources.xml
for both the databases.
Note the 'location' attribute corresponding to each
data-source.
Step 4. Associate the datasources
to the entities
The 'location' attribute corresponding to the data-source
configured as in Step 3. is used to associate the entities to the correct
database tables and columns. For the example application, verify that in
orion-ejb-jar.xml, the attribute 'data-source' corresponding
to each <entity-deployment> tag points to the correct
data-source.
Step 5. Deploy the application
using ANT tool and admin.jar
Ensure Ant 1.4.x or better is installed on your machine
and configured correctly.
Set JAVA_HOME and OC4J_HOME environment
variables. Note: On some operating systems Ant does not currently support
the use of environment variables, if this is the case for your operating
system, please modify the common.xml file located in 'ejb2pc'
directory.
This example assumes the default password for OC4J admin
to be 'welcome'. If you have a different password, please modify the password
in the ant build script i.e. build.xml as follows:
From the directory 'ejb2pc', [the directory where the
build.xml file is located], execute the following command :
> ant
This creates the application EAR file (ejb2pc.ear) in
ejb2pc\lib directory.
From the directory 'ejb2pc', [the directory where the
build.xml file is located], execute the following command to
deploy the application to the running instance of OC4J 10.0.3 started in
Step 2 :
> ant deploy-usingadmin.jar
Step 6. Run the application
Access the application in your favorite browser at the
URL : http://<hostname>:<port>/ejb2pc/Main.jsp
, where <hostname> is the host name of the server running OC4J 10g
instance and <port> is the OC4J HTTP port
For example : http://myoc4jserver:8888/ejb2pc/Main.jsp
This displays a form to add a new Order Item. Select
Order Id, Product Id and enter the price and quantity, and submit the details.
The new page displays the status of adding the New Order Item details. The
status can be re-checked by querying both the databases.
On selecting to delete an Order Item, the status of
deletion is displayed. The status can be re-checked by querying both the
databases.
Useful References
For more information, the following links will be useful.
Bookmark
