ObjectStore C++ API User Guide

Chapter 10

Support for the XA Standard for Transaction Processing

ObjectStore supports X/Open's transaction demarcation protocol (known as XA).

Distributed Transaction Processing Model
XA is a set of services that is part of the X/Open Distributed Transaction Processing (DTP) model. The model consists of three components: an application, a transaction manager, and a resource manager.

Transaction manager
In the DTP model, transaction demarcation is controlled by a transaction manager (TM).

The transaction manager can coordinate distributed transactions in multiple database systems so that, for example, one transaction can involve one or more processes and update one or more databases. The databases could be multiple ObjectStore databases or they could be incompatible databases, such as ObjectStore and Sybase.

Two-phase commit
Transactions under the control of a transaction manager are made through a two-phase commit process. In the first phase, transactions are prepared to commit; in the second, the transaction is either fully committed or rolled back.

Resource manager
An ObjectStore client acts as a resource manager (RM). Resource managers must be registered with the transaction manager.

Interface for applications
Applications are written using the transaction manager's API. XA is the interface between the transaction manager and the resource manager and is not visible to application programmers.

Transactions in the DTP Model

A global transaction is a metatransaction managed by a transaction manager and possibly involving multiple resource managers. Such transactions have globally unique identifiers generated by the transaction manager. Note that DTP global transactions are distinct from ObjectStore global transactions.

A transaction branch is a transaction from a resource manager's point of view.

A global transaction can consist of many transaction branches in a mix of resource managers. Multiple branches belonging to the same global transaction can exist on a single resource manager.

XA transactions are identified by XIDs (universally unique identifiers for global transactions). A branch has a globally unique ID composed of the global transaction ID and a branch ID.

XA transactions are always of the type update.

XA is also integrated into the OMG Object Transaction Service (OTS), which is based on DTP. The examples given show the use of Iona's OrbixOTS implementation of OTS.

An application that uses a transaction manager must use the TM's interface, for example, the OMG Object Transaction Service (OTS), to begin and end transactions. Other database operations can be done using the database systems' proprietary APIs. When recovery is required, the TM manages the process, using the XA interfaces to roll back or commit transactions that were in progress.

ObjectStore clients

ObjectStore and RDBMS database

Registering ObjectStore as a Resource Manager

You must register ObjectStore as a resource manager with your transaction manager.

Registering a resource manager provides basic identification information used in initialization and in processing transactions.

The information you must provide to register ObjectStore as a resource manager is packaged in a global data structure of type xa_switch_t. This data structure is defined in libos with the name ObjectStore_xa_switch.

In addition, for each ObjectStore resource manager, you must identify the hosts that will run ObjectStore Servers for applications that use the transaction manager.

There are several ways to register a resource manager. See your individual vendor documentation for specific information.

The Encina::Server::
RegisterResource function
The next example uses the OrbixOTS as the transaction manager and describes how to register a resource manager by passing a set of arguments to the Encina::Server::RegisterResource function.

Information for the following parameters is required:
xaSwitchPA pointer to a data structure of type xa_switch_t. Specify the symbol ObjectStore_xa_switch for ObjectStore resource managers.
openStringA string specific to the resource manager. For ObjectStore, this is a space-separated list of hosts running ObjectStore Servers that might be contacted by the ObjectStore client that is the resource manager. This list of Servers is queried during recovery operations.An attempt to contact a Server not in the list is considered an error.
closeInfoEmpty string.
isThreadAwareSpecifies the type of thread support. For ObjectStore resource managers, use the value False.
:

Intialization Example
The following example illustrates sample initialization code. 

extern struct xa_switch_t ObjectStore_xa_switch;
//  XA_OSTORE_SERVERS should be a space-delimited
//  list of ObjectStore Server host names. For example, 
// "host.domain.com host2.domain.com ..."  
char *openStringP = getenv("XA_OSTORE_SERVERS");
Encina::Server server;
// Register the database as a resource manager
server.RegisterResource(
      &ObjectStore_xa_switch, openStringP, "");

Using the Transaction Manager

 Once you have registered ObjectStore as a resource manager, you can use the transaction manager's interface to start and commit transactions.

Nested transactions
All transactions controlled by the transaction manager must be the top-level transaction. Nested DTP transactions are not allowed. Nested ObjectStore transactions are allowed within an XA transaction. These can be started and committed using the native ObjectStore interfaces.

If your program tries to start a transaction through the transaction manager when another transaction is already in progress, the transaction manager receives an error.

If your programs attempt to use the regular ObjectStore interface to commit or abort a transaction that was started by a transaction manager, one of the exceptions err_commit_xa or err_abort_xa is generated.

Concurrency modes
When ObjectStore is in use, the concurrency mode must be SERIALIZE_TRPCS_AND_TRANSACTIONS. ObjectStore can run only one transaction at a time, and this concurrency mode prevents the transaction manager from trying to start multiple concurrent transactions. Attempts to use other concurrency modes can result in the transaction manager's getting a deadlock error at the XA interface when starting a transaction.

Here is an example of using SERIALIZE_TRPCS_AND_TRANSACTIONS:

                                          server.Listen(Encina::Server::SERIALIZE_TRPCS_AND_TRANSACTIONS);

Two-Phase Commit and Recovery

The ObjectStore client refers to XA transactions by XID. The XID is saved in the Server's transaction log so that the Server, when queried after a crash, can provide a list of the XIDs of transactions that were prepared (phase 1 commit) but not committed (phase 2 commit).

Recovery is through the transaction manager and occurs during the initialization process for a DTP application.

Restrictions

There are some restrictions on the use of ObjectStore's native transaction interfaces when used with distributed transaction processing. Other ObjectStore interfaces can be used as usual.



[previous] [next]

Copyright © 1997 Object Design, Inc. All rights reserved.

Updated: 03/31/98 17:04:22