JBoss.orgCommunity Documentation

Chapter 2. Quick Start to JTS/OTS

2.1. Introduction
2.2. Package layout
2.3. Setting properties
2.4. Starting and terminating the ORB and BOA/POA
2.5. Specifying the object store location
2.6. Implicit transaction propagation and interposition
2.7. Obtaining Current
2.8. Transaction termination
2.9. Transaction factory
2.10. Recovery manager

2.1. Introduction

This chapter will briefly cover the key features required to construct a basic OTS application using the raw OTS interfaces defined by the OMG specification. It is assumed that the reader is familiar with the concepts of the JTS/OTS and has read the relevant ORB specific portions of the Programmer’s Guide. Further topics and the advanced facilities provided by will be described in subsequent sections of this manual; references to chapters in the other manuals of the document set will be given in the relevant sections.

2.2. Package layout

The key Java packages (and corresponding jar files) for writing basic OTS applications are:

All of these packages appear in the lib directory of the installation, and should be added to the programmer’s CLASSPATH.

In order to fully utilize all of the facilities available within , it will be necessary to add the some additional jar files to your classpath. See bin/setup-env.sh or bin\setup-env.bat for details.

2.3. Setting properties

has been designed to be highly configurable at runtime through the use of various property attributes, which will be described in subsequent sections. Although these attributes can be provided at runtime on the command line, it is possible (and may be more convenient) to specify them through the single properties file -properties.xml. At runtime looks for its property file in the following order:

Where properties are defined in both the system properties e.g. -Dfoo=bar and in the properties file, the value from the system property takes precedence. This facilitates overriding individual properties easily on the command line.

2.4. Starting and terminating the ORB and BOA/POA

It is important that is correctly initialized prior to any application object being created. In order to guarantee this, the programmer must use the initORB and initBOA/initPOA methods of the ORBInterface class described in the ORB Portability Manual. Using the ORB_init and BOA_init/create_POA methods provided by the underlying ORB will not be sufficient, and may lead to incorrectly operating applications. For example:

Example 2.1. Initialize ORB

 public static void main (String[] args) {

    ORBInterface.initORB(args, null);

    ORBInterface.initOA();

    //  . . .

} 

The ORBInterface class has operations orb() and boa()/poa()/rootPoa() for returning references to the orb and boa/child POA/root POA respectively after initialization has been performed. If the ORB being used does not support the BOA (e.g., Sun’s JDK 1.2) then boa() does not appear in the class definition, and initBOA will do nothing.

In addition, it is necessary to use shutdownOA and shutdownORB (in that order) prior to terminating an application to allow to perform necessary cleanup routines. shutdownOA routine will either shutdown the BOA or the POA depending upon the ORB being used.

Example 2.2. Shutdown ORB

 public static void main (String[] args) {

    // . . .

    ORBInterface.shutdownOA();

    ORBInterface.shutdownORB();

}

 

No further CORBA objects should be used once shutdown has been called. It will be necessary to re-initialise the BOA/POA and ORB in such an event.

Note

In the rest of this document we shall use the term Object Adapter to mean either the Basic Object Adapter (BOA) or the Portable Object Adapter (POA). In addition, where possible we shall use the ORB Portability classes which attempt to mask the differences between POA and BOA.

2.5. Specifying the object store location

requires an object store in order to persistently record the outcomes of transactions in the event of failures. In order to specify the location of the object store it is necessary to specify the location when the application is executed; for example: 

<!-- <br/> --><span class="java_plain">java&nbsp;</span><!-- <br/> --><span class="java_type">DObjectStoreEnvironmentBean</span><!-- <br/> --><span class="java_separator">.</span><!-- <br/> --><span class="java_plain">objectStoreDir</span><!-- <br/> --><span class="java_operator">=/</span><!-- <br/> --><span class="java_plain">var</span><!-- <br/> --><span class="java_operator">/</span><!-- <br/> --><span class="java_plain">tmp</span><!-- <br/> --><span class="java_operator">/</span><!-- <br/> --><span class="java_type">ObjectStore</span><!-- <br/> --><span class="java_plain">&nbsp;myprogram</span>

The default location is a directory under the current execution directory.

By default, all object states will be stored within the defaultStore subdirectory of the object store root, e.g., /usr/local/Arjuna/TransactionService/ObjectStore/defaultStore. However, this subdirectory can be changed by setting the ObjectStoreEnvironmentBean.localOSRoot property variable accordingly.

2.6. Implicit transaction propagation and interposition

Transactions can be created within one domain (e.g., process) and used within another. Therefore, information about a transaction (the transaction context) needs to be propagated between these domains. This can be accomplished in two ways:

OTS objects supporting the Control interface are standard CORBA objects. When the interface is passed as a parameter in some operation call to a remote server only an object reference is passed. This ensures that any operations that the remote object performs on the interface (such as registering resources as participants within the transaction) are performed on the real object. However, this can have substantial penalties for the application if it frequently uses these interfaces due to the overheads of remote invocation. To avoid this overhead supports interposition, whereby the server creates a local object which acts as a proxy for the remote transaction and fields all requests that would normally have been passed back to the originator. This surrogate registers itself with the original transaction coordinator to enable it to correctly participate in the termination of the transaction. Interposed coordinators effectively form a tree structure with their parent coordinators. This is shown in the figure below.

Interposition

Figure 2.1. Interposition relationship


Note

implicit transaction propagation does not imply interposition will be used at the server, but (typically) interposition requires implicit propagation.

If implicit context propagation and interposition are required, then the programmer must ensure that is correctly initialised prior to objects being created; obviously it is necessary for both client and server to agree on which, if any, protocol (implicit or interposition) is being used. Implicit context propagation is only possible on those ORBs which either support filters/interceptors, or the CosTSPortability interface. Currently this is JacORB and the JDK miniORB. Depending upon which type of functionality is required, the programmer must perform the following:

  • Implicit context propagation:

    set the JTSEnvironmentBean.contextPropMode property variable to CONTEXT.

  • Interposition:

    set the JTSEnvironmentBean.contextPropMode property variable to INTERPOSITION.

If using the advanced API then interposition is required .

2.7. Obtaining Current

The Current pseudo object can be obtained from the com.arjuna.ats.jts.OTSManager class using its get_current() method.

2.8. Transaction termination

It is implementation dependant as to how long a Control remains able to access a transaction after it terminates. In , if using the Current interface then all information about a transaction is destroyed when it terminates. Therefore, the programmer should not use any Control references to the transaction after issuing the commit/rollback operations.

However, if the transaction is terminated explicitly using the Terminator interface then information about the transaction will be removed when all outstanding references to it are destroyed. However, the programmer can signal that the transaction information is no longer required using the destroyControl method of the OTS class in the com.arjuna.CosTransactions package. Once the program has indicated that the transaction information is no longer required, the same restrictions to using Control references apply as described above.

2.9. Transaction factory

By default, does not use a separate transaction manager when creating transactions through the Current interface. Each transactional client essentially has its own transaction manager (TransactionFactory) which is co-located with it. By setting the com.arjuna.ats.jts.transactionManager property variable to YES this can be overridden at runtime. The transaction factory is located in the bin directory of the distribution, and should be started by executing the start-transaction-service script located in <ats_root>/bin.

Typically Current locates the factory using the CosServices.cfg file. This file is similar to resolve_initial_references, and is automatically updated (or created) when the transaction factory is started on a particular machine. This file must be copied to the installation of all machines which require to share the same transaction factory. CosServices.cfg is located at runtime by the OrbPortabilityEnvironmentBean properties initialReferencesRoot (a directory, defaulting to the current working directory) and initialReferencesFile (a name relative to the directory,'CosServices.cfg' by default).

It is possible to override the default location mechanism by using the OrbPortabilityEnvironmentBean.resolveService property variable. This can have one of the following values:

If OrbPortabilityEnvironmentBean.resolveService is specified when the transaction factory is run, then the factory will register itself with the specified resolution mechanism.

2.10. Recovery manager

You will need to start the recovery manager subsystem to ensure that transactions are recovered despite failures. In order to do this, you should run the start-recovery-manager script in <ats_root>/bin.