Table of Contents
This document provides all information on how to download, install, run and test the OpenORB TransactionService.
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:
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.
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.
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.
Table of Contents
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.
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:
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.
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 locationThe 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.
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).
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 and ots_examples-{version}.jar. When running on JDK 1.3 the jdbc2_0-stdext.jar must also be included (these classes are part of JDK 1.4 and higher).
WithoutResource:
java org.openorb.ots.examples.withoutres.BankServer -ORBProfile=ots
java org.openorb.ots.examples.withoutres.BankClient -ORBProfile=ots
WithResource:
java org.openorb.ots.examples.withres.BankServer -ORBProfile=ots
java org.openorb.ots.examples.withres.BankClient -ORBProfile=ots
SubTransaction:
java org.openorb.ots.examples.subtrx.BankServer -ORBProfile=ots
java org.openorb.ots.examples.subtrx.BankClient -ORBProfile=ots