EJB Transactions across Database Links

Table of Contents 

• Overview of the application
• Required Software
• Notations used
• Extracting the source code 
• Configuring the application 
• Deploying and Running the application using Oracle9i JDeveloper
• Deploying and Running the application using ANT
• Description of Sample Files

This Sample illustrates EJB Transactions across Database Links. This Sample also demonstrates how to handle transactions using Server Side Java Transaction Service (JTS).

The Sample assumes that there exists a user 'GLOBAL_ECONOMY' apart from 'Travel' user. The user 'GLOBAL_ECONOMY' has a single table called 'EXCHANGE_RATES'. The user 'GLOBAL_ECONOMY' can be in the same database or different database.

The Sample application prompts the user to select Home Country and Destination Country. User can then enter the current exchange rate between these two countries and press "UPDATE EXCHANGE RATE" button. Upon pressing "UPDATE" button, the method 'updateExchangeRate()' from the EJB 'ExRateBean' is invoked. This method is responsible for updating the exchange rates data in both 'GLOBAL_ECONOMY' and 'TRAVEL' user. This method does this updating transaction using a Database Link connecting 'GLOBAL_ECONOMY' user to 'TRAVEL' user.

Note :
1) The Exchange Rate Data in both the user is always in consistent State. That is, the above method either commits the data in both the user or rollbacks the transaction if any of the update statement fails.

2) The bean implementation uses the javax.jts.UserTransaction interface methods to manage transactions on its own.

Steps in the Sample

1. The user invokes the application and the application connects to database and shows the Status of the Connection.
2. If the Connection was successful, it populates Home Country JTable and Destination Country JTable from Countries Table.
3. User can select Home Country and Destination Country from these JTables. After selecting Home Country and Destination Country, the user can enter latest Exchange Rate and press "UPDATE EXCHANGE RATE" button.
4. Upon pressing the "UPDATE EXCHANGE RATE" button, the method 'updateExchangeRate()' from the EJB 'ExRateBean' is invoked. This method is responsible for updating exchange rates data in both the users 'GLOBAL_ECONOMY' and 'TRAVEL'.
5. When user presses 'EXIT', the application exists. 

The software required for running the sample are : 

• Oracle9iAS (9.0.2.0.0) Containers for J2EE (or higher) downloadable from here 
• Oracle9i Database Release 9.0.2 (or higher) - Production downloadable from here
• Oracle9i JDeveloper 9.0.3 downloadable from here (or) Ant Version 1.5 downloadable from here 

This following notations are used through out this document
 

Notation	Description
<OC4J_HOME>	Folder where OC4J is installed. For example, D:\oc4j
<SAMPLE_HOME>	Folder where the EJBTrans sample will be unzipped. For example, C:\OTNSamples
<JAVA_HOME>	Folder where JAVA is installed. For example, C:\jdk1.2
<ANT_HOME>	Folder where the ANT is installed. For example, C:\ant

 
 

Extracting the source code

Back To Top

Execute the following command to extract the sample application. In windows environment, this file can also be opened using Winzip utility.
 

> jar xvf EJBTrans.jar

The above command extracts all the sample files to EJBTans folder. Click here to view the directory structure and description of sample files
 
 
 

Configuring the application

Back To Top

Preparing the Database

Step 1: Ensure that 'Travel Schema' is loaded into the database. For more details about loading the Travel Schema Click here.

Step 2: Execute <SAMPLE_HOME>\EJBTrans\database\ejbTrans.sql. This SQL Script will prompt for database system password, database sid, database host name and listener port number. This script creates GLOBAL_ECONOMY user and the Database link named dblink4, which links to the travel schema.

Step 3: Edit <SAMPLE_HOME>\config\config.properties. Provide SecurityPrincipal and SecurityCredentials. These values will be used while looking up the EJB, by the Client program.

This section describes the steps required in deploying this application to the Standalone OC4J using Oracle9i JDeveloper

Step 1:. Open the <SAMPLE_HOME>\EJBTrans\EJBTrans.jws in Oracle9i JDeveloper. The workspace contains EJBTrans.jpr (project file), deployment files and other files.

Step 2: Create Database Server Connection 

1. Select Database Server under the Connections Node.
2. Right click on Database Servers and select "New Connection".
3. In Step 1 of the wizard, Enter the Connection Name as 'Travel'.
4. In Step 2 of the wizard, Provide 'travel' as user name and password for the travel schema. (by default travel).
5. In Step 3 of the wizard, Provide the appropriate database connection information where travel schema is loaded. 
6. In Step 4 of the wizard, Test the connection and Select 'Finish' button 

Step 3: Create Standalone OC4J Connection 

1. Select Application Server under the Connections Node.
2. Right click on Application Servers and select "New Connection".
3. In Step 1 of the wizard, Enter the Connection Name and select Connection Type as 'Standalone OC4J'
4. In Step 2 of the wizard, Provide 'admin' user name and password for the admin user.
5. In Step 3 of the wizard, Check if the URL targets to the machine, where OC4J runs.
6. In Step 4 of the wizard, Test the connection and Select 'Finish' button. Ensure that Standalone OC4J is started.

Step 4: Deploy the EJB to the Standalone OC4J

1. Right click ExRateEJB.deploy under EJBTrans.jpr
2. Select 'Deploy to ' the connection created in Step 3.

This deploys the EJB to the Standalone OC4J.

Step 5: Right click EJBTrans.jpr and select "Make EJBTrans.jpr". This compiles all the java classes in the project.

Step 6: Right click EJBTans.jpr and select "Run EJBTrans.jpr". This runs the ExRateEJBClientSample.java
 
 

Deploying and Running the application using ANT

Back To Top

This section describes the steps required in deploying this application to the Standalone OC4J using ANT Tool.

Step 1:  SET Environment Variables

1. Open the Command Prompt and Go to the <SAMPLE_HOME>\EJBTrans directory
2. Ensure that <JAVA_HOME>\bin is in the PATH
3. Ensure that <ANT_HOME>\bin is in the PATH

Step 2:  Build the EAR file
 

From <SAMPLE_HOME>\EJBTrans, execute ant 
 

<SAMPLE_HOME>\EJBTrans>ant

    This will create the EJBTrans.ear file.

Step 3: Having created a EJBTrans.ear file, to deploy this application to Standalone OC4J, use the following command, from <SAMPLE_HOME>/EJBTrans directory.
 

> java -jar <OC4J_HOME>\j2ee\home\admin.jar ormi://localhost:23791 admin <oc4j password> -deploy -file <SAMPLE_HOME>\EJBTrans\EJBTrans.ear -deploymentName EJBTrans For example, > java -jar D:\oc4j\j2ee\home\admin.jar ormi://localhost:23791 admin welcome -deploy -file C:\OTNSamples\EJBTrans\EJBTrans.ear -deploymentName EJBTrans

Step 4:  Add data source to the application

Execute the following command, substitute database host name, database listening port and database sid appropriately.
 

> java -jar <OC4J_HOME>\j2ee\home\admin.jar ormi://localhost:23791 admin <oc4j password> -application EJBTrans -installDataSource -url jdbc:oracle:thin:@<DB_HOST>:<DB_PORT>:<DB_SID> -location jdbc/TravelDS -username travel -password <schema password> -connectionDriver oracle.jdbc.driver.OracleDriver -className oracle.jdbc.pool.OracleConnectionPoolDataSource  For example, > java -jar D:\oc4j\j2ee\home\admin.jar ormi://localhost:23791 admin welcome -application EJBTrans -installDataSource -url jdbc:oracle:thin:@demo.oracle.com:1521:orcl -location jdbc/TravelDS -username travel -password travel -connectionDriver oracle.jdbc.driver.OracleDriver -className oracle.jdbc.pool.OracleConnectionPoolDataSource

Step 5:  Run the sample

Add the following class libraries to the class path and execute the jar.

<OC4J_HOME>/j2ee/home/oc4j.jar
<OC4J_HOME>/jdbc/lib/classes12.jar
<OC4J_HOME>/j2ee/home/lib/ejb.jar
<SAMPLE_HOME>/EJBTrans/EJBTrans-client.jar

and execute the following command

>java oracle.otnsamples.ejbtrans.client.ExRateEJBClientSample

                   

Description of sample files

Back To Top

Directory	Filename	Description
EJBTrans	build.xml	This XML file is used by ANT to create the application ear file
	EJBTrans.jws	JDeveloper WorkSpace File
	EJBTrans.jpr	JDeveloper Project file
	ExRateEJB.deploy	EJB Deployment Profile
EJBTrans\src\oracle\otnsamples\ejbtrans\ejb	ExRateRemote.java	This is Remote interface defines of the ExRate EJB
	ExRateHome.java	This is the Home Interface of the ExRate EJB
EJBTrans\src\oracle\otnsamples\ejbtrans\ejb\impl	ExRateBean.java	This is the bean implementation class of the ExRate EJB
EJBTrans\src\oracle\otnsamples\ejbtrans\client	ExRateEJBClientFrame.java	This class brings up GUI for the ExRateEJB Client
	ExRateEJBClientSample.java	This class contains business logic to invoke the ExRateEJB Client
EJBTrans\src\oracle\otnsamples\ejbtrans\utils	GridBagConstraints2.java	This utility class extends GridBagConstraint by overloading the constructor.
	SysSetting.java	This class reads the properties from the config.properties file.
	GenTableModel.java	Table model class used for Table GUI
EJBTrans\database	ejbTrans.sql	SQL Script creates GLOBAL_ECONOMY user and database link
EJBTrans\docs	Readme.html	This file. It contains description about the sample and steps to deploy and run the sample.
EJBTrans\config	application.xml	This XML describes the sample application.
	ejb-jar.xml	This XML describes the Mailer EJB
	config.properties	This file contains sample properties.

Please enter your comments about this sample in the OTN Sample Code Discussion Forum.