The Community OpenORB - TransactionService

Marina Daniel

Gary Shea


Table of Contents

Introduction
1. Overview
2. Compilation
3. Installation
4. Configuration
5. Deployment
Launching Supporting Services
Launching the Transaction Service
Transaction Logs
About Databases
Virtual XA Management
OpenORB Transaction Service Examples
6. Frequently Asked Questions
A. Appendix

Introduction

This document provides all information on how to download, install, run and test the OpenORB TransactionService.

Chapter 1. Overview

The Transaction Service is a fully compliant implementation of the OMG OTS 1.1 specification. OpenORB Transaction Service is a very scalable transaction monitor which also provides several extensions like XA management, a management interface to control all transaction processes and a high reliable recovery system.

Its main features are:

  • Management of distributed transactions with a two phase commit protocol
  • Propagation of the transaction context between CORBA objects
  • Management of distributed transactions propagation through databases with the XA protocol
  • Automatic logs to be able to make recovery in case of failures
  • Can be used as a transaction initiator or subordinate
  • High-performance, multiple thread architecture
  • Developed with POA
  • Provides a management interface to control all transactions
  • Full support of JTA
  • JDBC pooling and automatic resource enlistment

Chapter 2. Compilation

If building from source distributions, the OpenORB core source distribution directory is required. Follow the directions in that distribution to build the core. Do not delete the core distribution before attempting to build the Transaction Service. Unpack the Transaction Service so that the TransactionService sub-directory is in the same directory as the OpenORB sub-directory. This will insure that all dependencies are resolved, as a number of jars required to build the TransactionService are either part of, or built by, the OpenORB core distribution.

If building from CVS, checkout and build the OpenORB directory first.

The Transaction Service distribution contains an Ant buildfile (src/build.xml) to coordinate the build.

To compile the OpenORB Transaction Service, enter one of the the following commands from the command line. For Windows/DOS: build or for Unix: sh build.sh

The build will create a dist directory containing the openorb_ots-{version}.jar file, the other jars required by the Transaction Service, the javadoc documentation, and this document.

Chapter 3. Installation

This chapter explains how to install the OpenORB Transaction Service. We remind you that OpenORB is required and must be previously installed before proceeding to the next steps. You need the OpenORB distribution to use the OpenORB Transaction Service.

To get the OpenORB Transaction Service, visit the OpenORB web site (http://openorb.sf.net). Then, go to the download section. Follow the instructions to download the Transaction Service.

Chapter 4. Configuration

The configuration and all the services information are located in the OpenORB.xml file. For more information about this configuration file, please refer to the OpenORB documentation.

A file ots.xml is provided in the src/config directory of the Transaction Service distribution.

To be in a transactional context, you will have to launch your applications with the -ORBProfile=ots flag where ots is the profile name that is defined in the OpenORB.xml configuration file

To complete the configuration, we have to replace the embedded configuration by the new one. The way to do that depends on the distribution that you are currently using : source code or pre built distribution. The following paragraphs describes how to proceed for each distribution kind.

Chapter 5. Deployment

Launching Supporting Services

Start a Naming Service. Either the standard naming service or the extended naming service may be used. Directions for each are given below:

[Standard Naming Service]: The Naming Service requires that the CLASSPATH contain openorb-{version}.jar. java -ORBPort=2001 org.openorb.util.MapNamingContext Port 2001 is the default port in the shipped OpenORB configuration file.

[Extended Naming Service]: The Extended Naming Serivce requires that the CLASSPATH contain openorb-{version}.jar, openorb_ins-{version}.jar, openorb_pss-{version}.jar, avalon-framework.jar, and openorb_ots-{version}.jar. java -ORBPort=2001 org.openorb.ins.Server Port 2001 is the default port in the shipped OpenORB configuration file.

Launching the Transaction Service

The Transaction Serivce requires that the CLASSPATH contain openorb-{version}.jar and openorb_ots-{version}.jar. For database applications jdbc2_0-stdext.jar is required; for applications using the XA protocol, jta_1.0.0.jar is required; if using the Extended Naming Service, openorb_ins-{version}.jar is required.

java org.openorb.ots.Server -ORBProfile=ots (-naming or -ior or -recover)

One of the -naming, -ior, or -recover flags must be given when the OTS Server is launched:

  • -naming: That will export the transaction factory in the naming service with the following path: COS\TransactionService\TransactionFactory.
  • -ior: By specifying this flag, the OpenORB OTS Server will generate a file named ots.ior that will contain the OpenORB OTS Server reference. (It corresponds to the Transaction Factory object reference)
  • -recover: After a failure, and if you have activated the transaction logs, you have to start the OpenORB OTS Server with this flag. The OpenORB OTS Server will continue all non finished transactions.

Transaction Logs

A Transaction Log is a file that contains all information about transaction processing. If the OpenORB OTS Server stops abnormaly (due to any kind of failure), it will be possible to recover all non finished transactions.

About Databases

To allow the OpenORB Transaction Service to manage transactions with databases, additional configurations have to be set. First of all, each database is associated to a profile. Each profile is configured into the OpenORB.xml configuration file and provides the following sub entries:

profile_name.XA.VirtualXA = true or false profile_name.JDBC.driver_loading = true or false profile_name.JDBC.driver = jdbc.idbDriver for jdbc profile_name.JDBC.isolation_level = "4" for example profile_name.JDBC.url = jdbc:idb:XXX , XXX= your location

The first property is explained in the section below. The other properties provide information about the database: driver_loading: this entry is used to know if the OpenORB OTS Server has to load the JDBC driver. driver: if the value of the previous entry is true, you have to specify here the JDBC driver class name. JDBC.url: the URL to use to open a connection.

An example of what you have to insert in your OpenORB.xml file is available in the ots.xml file in the src/config directory.

Virtual XA Management

To be able to control a transaction into a database, a specific protocol has been defined: XA Protocol. The JDBC 2.0 specification describes an extension to provide XA management via the JDBC driver and the JTA interfaces. Unfortunately, there are few JDBC drivers that support the extension of XA. OpenORB OTS Server provides a XA extension that encapsulates a standard JDBC driver. So, even if you use a JDBC driver that does not support the XA extension, the OpenORB Transaction Service will be able to add a virtual XA extension to manage distributed transactions. To activate the virtual XA management for a database, set to true the XXXXX.XA.VirtualXA property (where XXXXX is the database profile).

OpenORB Transaction Service Examples

If you have built the Transaction Service with the build or sh build.sh command, the Transaction Service examples are already built. You will find the ots_examples-{version}.jar file in the dist directory of the Transaction Service distribution. If necessary, use the following command to build the OTS examples: build examples

Before launching the examples, you must first launch a naming service and the Transaction Service. Follow the directions given in the Launching Supporting Services and Launching the Transaction Service sections.

Note that the example clients and servers must be able to find the Naming Service. If using the distributed OpenORB configuration, the example programs will look for the naming service on port 2001 of localhost.

For all examples, both the client and the server require that the CLASSPATH contain openorb-{version}.jar, openorb_ots-{version}.jar, ots_examples-{version}.jar, and jdbc2_0-stdext.jar.

WithoutResource: java WithoutResource.BankServer -ORBProfile=ots java WithoutResource.BankClient -ORBProfile=ots

WithResource: java WithResource.BankServer -ORBProfile=ots java WithResource.BankClient -ORBProfile=ots

SubTransaction: java SubTransaction.BankServer -ORBProfile=ots java SubTransaction.BankClient -ORBProfile=ots

Chapter 6. Frequently Asked Questions

Set

6.1. ?
6.1.

?

!

Appendix A. Appendix