How-To : Propagate a transaction context from one OC4J instance to another using ORMI

Date: 1/18/06
Author: Debu Panda

• Introduction
  • What is Transaction Context Propagation
  • How to propagate transaction context using ORMI
• Prerequisites
  • What you need to know
  • Software requirements
  • Notations
• Building the Application
• Running the Application
  • Examine the Sample File Directories
  • Configure the Environment
  • Start OC4J
  • Generate, Compile and Deploy the Application
  • Run the application
• Summary

Introduction

This example application demonstrates Oracle's support for the transaction context propagation between OC4J instances using ORMI.

What is Transaction Context Propagation

Transaction context propagation is necessary if multiple OC4J instances are to participate in a single distributed transaction. A transaction context defines the scope of a transaction and associates all participating resources and transactional operations. All participating threads share the same transaction context.

Multiple OC4J instances need to participate in the same transaction if an OC4J instance makes a remote call into another OC4J instance in the scope of an existing transaction, assuming the EJB semantics for the method support scoping work in a client’s transaction. An example of this is a servlet in OC4J instance 1 obtaining a reference to an EJB residing in OC4J instance 2, starting a transaction and making a method call on the remote EJB in the scope of the transaction. When multiple OC4J instances participate in a single transaction, all work done by the participating OC4J instances as part of the global transaction is guaranteed to be atomic.

How to Propagate Transaction Context Using ORMI

There are no special settings required in the container to propagate transaction context between OC4J instances. However, you must configure the Transaction Manager logging to ensure recovery of failed/in-doubt transactions. You have to invoke a remote EJB in a transactional context using RMIInitialContextFactory as in the following code:

		 env.put(Context.INITIAL_CONTEXT_FACTORY, "oracle.j2ee.rmi.RMIInitialContextFactory");
      env.put(Context.PROVIDER_URL, "ormi://localhost:23792/TxProp");
      env.put(Context.SECURITY_PRINCIPAL, "oc4jadmin");
      env.put(Context.SECURITY_CREDENTIALS, "welcome");

Prerequisites

What you need to know

• EJB 2.x
• Transactions

For further information on OC4J, see the following documents on OTN:

• Link to other OC4J Howto's on OTN

Software Requirements

This demonstration requires that the following software components are installed and configured correctly:

• Oracle Application Server 10g (10.1.3)
• Sun JDK version 1.4.1 or above, available here
• Any HTML browser like Mozilla, Microsoft Internet Explorer, Netscape, etc.
• A relational database such as Oracle.

Notations

• %ORACLE_HOME% - The directory where you installed the Oracle Application Server 10g (10.1.3)
• %JAVA_HOME% - The directory where your JDK is installed
• %HOWTO_HOME% - The directory where this demo is unzipped

Building the Application

The configuration files are located in the %HOWTO_HOME%/etc directory, including deployment descriptor files such as application.xml.

Running the Application

To run the sample application on an instance of Oracle Application Server 10g 10.1.3 , follow these steps:

1. Examine the Sample File Directories

• build - temporary directory created during the build
• log - temporary directory holding build/deploy logs
• etc - all necessary files to package the application
• lib - holds the application archives that could be deployed
• script - contains SQL script to create a table
• doc - the How-to document and Javadoc's
• javadoc - the javadoc of the different source files
• how-to-transaction-propagation.html - this How-to page
• src - the source of the demo
  • ejb - contains the sample entity bean code
  • web- contains application

2. Configure the Environment

Ensure the following environment variables are defined:

• %ORACLE_HOME% - The directory where you installed OC4J.
• %JAVA_HOME% - The directory where you installed the J2SE 5.0

Configure Database

Create the table using the table.sql script in the %HOWTO_HOME%/scripts directory.

Configure Data Source

This example requires a DataSource to be configured to connect to the database that contains the DESTINATION table.

For OC4J, you must configure a datasource in the %ORACLE_HOME%/j2ee/home/config/data-sources.xml file and point it at the schema that owns the DESTINATION table.

An example configuration:

<connection-pool name="ScottConnectionPool">
  <connection-factory factory-class="oracle.jdbc.pool.OracleDataSource"
   user="scott"
   password="tiger"
   url="jdbc:oracle:thin:@localhost:1521:ORCL" >
  </connection-factory>
</connection-pool>

<managed-data-source name="OracleManagedDS"
 connection-pool-name="ScottConnectionPool"
 jndi-name="jdbc/OracleDS"
/> 

Start OC4J stand alone using the following command after you make the above changes.

>%ORACLE_HOME%/bin/oc4j -start

If you are using an OracleAS managed install, start using the following command after you make the above changes.

> %ORACLE_HOME%/opmn/bin/opmnctl startall

4. Generate, Compile, and Deploy the Application

Ant 1.6.2 is shipped with OC4J and you have to set your PATH environment variable to $ORACLE_HOME/ant/bin. 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 ant-oracle.xml file located in the %HOWTO_HOME% directory.

Edit ant-oracle.properties (in the demo directory) and ensure the following properties are set to the correct values, as indicated below for both OC4J instances :

• oc4j.host: host where OC4J is running (default localhost)
• oc4j.admin.port: RMI port number (default 23791)
• oc4j.admin.user: admin user name (default oc4jadmin)
• oc4j.admin.password: admin user password (default welcome)
• oc4j.binding.module: website name where deployed web modules are bound (default http-web-site)

If you are using OracleAS managed install then you have appropriately change the following properties beside changing oc4j.admin.user and oc4j.admin.password for your managed OC4J instance in OracleAS install.

• opmn.host: the hostname/IP where OracleAS is running (default localhost)
• opmn.port: OPMN request port (default 6003) for the OracleAS install
• oc4j.instance: admin user name (default oc4jadmin)

You have to uncomment appropriate deployer.uri in the ant-oracle.properties based on your environment i.e. a single instance OC4J or a clustered OC4J instance/group managed by OPMN.

Code Changes Required in an OracleAS instance

You have to make appropriate changes in the createContext method of TXPropagationBean.java while per your environment. You have to use opmn:ormi lookup when looking up an EJB in an OracleAS environment where OC4J instance is managed by OPMN and ORMI port is dynamically allocated.

Building and Deploying

>ant deploy

5. Run the Application

Run the sample by providing invoking the following URL from your favorite browser:

http://localhost:port/TxProp

In this page, enter appropriate data, select appropriate button for transaction option and then click on Execute Demo.

If a transaction does exist, the method will execute using the existing transactional context. When the JSP calls a method on an EJB in process 1, a transaction is started. The EJB in process 1 then calls an EJB in process 2, which causes the transaction to be propagated to process 2. The EJB in process 2 executes using the propagated transaction context. A database insert is done by the bean on process 2 and then by the bean on process 1 when the call to the bean in process 2 returns.

Three different scenarios are executed.

1. The transaction commits and both records are inserted into the database.
2. The EJB running on process 1 marks the transaction for rollback, which causes the transaction to ultimately rollback.
3. The EJB running on process 2 marks the transaction for rollback, which causes the transaction to ultimately rollback.

Summary

In this document, you should have learned :

• What is transaction context propagation
• How do you propagate transaction between OC4J instances
• Deploy an execute the simple transaction context propagation sample using two OC4J instances