OracleAS TopLink - How to enable OracleAS Toplink to work with
external transaction controller (J2EE)

Date: 15/04/2004

Table of Contents

Introduction 

Oracle Application Server TopLink is an advanced object-to-relational persistence. It helps to build high performance applications that store persistent data in a relational database. OracleAS TopLink provides transaction controllers for container-specific support, as well as a generic controllers that can be used for other specification-conforming servers.

Prerequisites 

• You must have little knowledege OracleAS Toplink Mapping Workbench and Sessions Editor
  

Software Requirements 

• Oracle Database 10g installed with HR Schema
• OracleAS TopLink 10g

HowTo enable OracleAS Toplink to work with external Transaction Controller

A transaction controller is a TopLink class that synchronizes the session cache with the data on the database. The transaction controller manages messages and callbacks from the J2EE transaction. On commit, the transaction controller executes the Unit of Work SQL on the database, and merges changed objects into the TopLink session cache. Toplink provides support for external datasources and external transaction controllers. Because JTA transaction controllers require a JTA-enabled DataSource, an external transaction controller has to be configured with TopLink external connection pool support.

External transaction controller can be configured with the following steps.

i) Configure JTA enabled DataSource on the J2EE server

In OC4J, add the following entry in the <J2EE_HOME>/config/data-sources.xml or to the application specific data-sources.xml.
Where <J2EE_HOME> is the folder in which OC4J is installed.

<data-source name="OracleDS" class="com.evermind.sql.DriverManagerDataSource" location="jdbc/OracleCoreDS" xa-location="jdbc/xa/OracleXADS" ejb-location="jdbc/OracleDS" pooled-location="jdbc/OraclePooledDS" connection-driver="oracle.jdbc.driver.OracleDriver" username="hr" password="hr" url="jdbc:oracle:thin:@localhost:1521:ORCL" inactivity-timeout="30"/>

ii) Add the following elements to the login tag in the sessions.xml file to specify a DataSource and a TopLink external connection pool.

 

<datasource>jdbc/OracleCoreDS</datasource> <uses-external-transaction-controller>true </uses-external-transaction-controller> <uses-external-connection-pool>true </uses-external-connection-pool>

Iii) Specify an external transaction controller class in the sessions.xml file.

<external-transaction-controller-class> oracle.toplink.jts.oracle9i.Oracle9iJTSExternalTransactionController </external-transaction-controller-class>

iv) While using JTA, inorder to ensure that there is only one Unit of Work associated with a given transaction, we need to use getActiveUnitOfWork method to acquire a Unit of Work in the JTA transaction.

UnitOfWork uow = clientSession.getActiveUnitOfWork();

If null is returned then no transaction is active, and one must be started by acquiring a new Unit of Work using the acquireUnitOfWork method.

if(uow==null) uow = clientSession.acquireUnitOfWork();

Steps to run the sample 

• Extract the jar file
• Edit <SAMPLE_HOME>/src/META-INF/data-sources.xml to point to your database installation.
• Set the following environment variables
• OC4J_HOME to the OC4J installation directory 
• OC4J_HOST to the machine where OC4J is running.
• OC4J_USER to the admin user name
• OC4J_PASSWORD to the admin password
• JAVA_HOME to the  J2SDK 1.4.x installation directory
• ANT_HOME to the ANT 1.4.1 installation directory
• Make sure that <JAVA_HOME>/bin and <ANT_HOME>/bin are in PATH
  
• From <SAMPLE_HOME> directory run,
• ant -this will deploy the application to OC4J 10g
• Access the following URL
              http://<HOST_NAME>:<HTTP_PORT>/J2EETransactionSample/listEmployees.jsp
  
  
• The listEmployees.jsp will list all the employees whose employee number is between 150 to 159. This listEmployees.jsp page uses EmployeeManagementBean.java which inturn uses stateless EJB(HRSessionEJBBean). This EJB uses Toplink with external transaction controller to read employee details.
• Clicking on Employee number will list employee details in which salary and commision percentage are updateable. This update feature uses Toplink with external transaction controller.
  

Useful References 

• OracleAS TopLink 10g
• OracleAS TopLink Discussion Forum