XA Proposal

Resolution for issue #3157 (need interoperable XA support):

Resolution for issue #3536: OTS interoperability - need for unique branch ids

A.2.1 Introduction

With the Transaction Service, this is achieved by implementing CosTransactions::Resource objects -- each resource represents a local transaction in the transactional system -- and registering these Resource objects with the distributed transactions.

Since many systems provide a standard interface to their transactional capabilities -- the XA interface -- it is possible to implement CosTransactions::Resource objects on top of the XA interface, and provide an easy to use integration with the Transaction Service. The same integration (with the same interfaces and behavior) may also be provided through proprietary interfaces provided by a given Transaction Service implementation, without the creation and registration of CosTransactions::Resource objects. See Figure 1.
 

The Java Transaction API Specification [JTA] defines the Java equivalent of the XA interface (javax.transaction.xa.XAResource) and a set of local Java interfaces that provide a "higher level" API to the Transaction Service (the interfaces are defined in the javax.transaction package). JTA also specifies the standard integration between the Transaction Service and Resource Managers that implement the Java XAResource interface.

For implementations in Java, JTA when available, is the preferred standard integration API between the Transaction Service and XA Resource Managers. Note, JTA is the standard Transaction Service/XA Resource Manager integration API for implementations in Java compatible with the J2EE platform [J2EE].

This section specifies the interfaces for the standard integration between the Transaction Service and C XA resource managers [1]. Unlike JTA, this section does not define a higher level API to the Transaction Service: it relies directly on the Transaction Service types defined in the CosTransactions module.

This XA integration can be implemented using the standard Transaction Service interfaces; as a result, it may be provided by a Transaction Service vendor, a Resource Manager vendor, or any other third party. Likewise the integration with Resource Managers that implement the Java XAResource interface can be provided by a Transaction Service vendor, a Resource Manager vendor, or any other third party. A compliant Transaction Service implementation may, but does not need to, provide any or both of these standard integrations.
 

A.2.2 XA-compatible Transaction Service

• The Transaction Service does not restrict the availability of the PropagationContext: the operation get_txcontext  on the Coordinator never raises Unavailable.

• The format of each otid_t value generated by the Transaction Service must correspond to the XID format, that is:
• the bqual_length must be between 1 and 64
• the tid length must be between bqual_length + 1 and bqual_length + 64
• the gtrid (global transaction id) is provided by the first bytes in tid; the following bqual_length bytes correspond to the bqual (branch qualifier) part of the XID.
• Transactions in unrelated transaction families have distinct otid_t values.
• otid_t values generated by different XA-compatible Transaction Service implementations are always distinct.

This is achieved by assigning formatIDs to Transaction Service implementations: each XA-compatible Transaction Service implementation  must use its own formatID value. formatID values other than 0 and -1 [2] are assigned by the OMG. Allocation of formatIDs may be requested by sending email to tag-request@omg.org.

A.2.3 XA Overview

XA defines a set of C-function pointers, and a C-struct that holds these function pointers, xa_switch_t:

/*
 *  From Appendix A of the XA specification:
 */

struct xa_switch_t {
 char name[RMNAMESZ];          /* name of resource manager */
 long flags;                   /* resource manager specific options */
 long version;                 /* must be 0 */
 int (*xa_open_entry)          /* xa_open function pointer */
     (char *, int, long);
 int (*xa_close_entry)         /* xa_close function pointer */
     (char *, int, long);
 int (*xa_start_entry)         /* xa_start function pointer */
     (XID *, int, long);
 int (*xa_end_entry)           /* xa_end function pointer */
     (XID *, int, long);
 int (*xa_rollback_entry)      /* xa_rollback function pointer */
     (XID *, int, long);
 int (*xa_prepare_entry)       /* xa_prepare function pointer */
     (XID *, int, long);
 int (*xa_commit_entry)        /* xa_commit function pointer */
     (XID *, int, long);
 int (*xa_recover_entry)       /* xa_recover function pointer */
     (XID *, long, int, long);
 int (*xa_forget_entry)        /* xa_forget function pointer */
     (XID *, int, long);
 int (*xa_complete_entry)      /* xa_complete function pointer */
     (int *, int *, int, long);
};

Each XA-capable system must provide a global instance of xa_switch_t.

The function pointers provided by this xa_switch_t instances can be divided in four categories:

• functions to connect and disconnect to the XA resource manager:

xa_open() and xa_close()
The string passed to xa_open() typically contains connection information, e.g. a database name and a username and password.
 
• transaction completion functions:

xa_prepare(), xa_commit(), xa_rollback(), xa_forget()
They correspond to the CosTransactions::Resource operations.
 
• recovery functions

xa_recover()
 
• functions used to start and end associations between connections and a transactions:

xa_start(), xa_end()
In order to use an XA connection to do some work within a distributed transaction, it is necessary to create an association between this connection and the distributed transaction. xa_start() is used to create such an association; xa_end(TMSUSPEND) suspends the association, without releasing the connection; xa_start(TMRESUME) resumes a suspended association; xa_end(TMSUCCESS) terminates an association with success, and xa_end(TMFAIL) terminates an association and marks the transaction rollback-only.

A.2.4 XA and Multi-Threading

• a thread-unsafe mode, in which the scope of each XA connection is the process (XA thread-of-control maps to process)
• a thread-safe mode, in which the scope of each XA connection is the thread by which is was created (XA thread-of-control maps to thread)

The main drawback of tying connections and threads is flexibility since it prevents the application from managing connections independently of threads, which limits a lot the kind of connection pooling that can be implemented. Also, a CORBA server typically dispatches different requests to different threads: the thread of control equal thread model prevents the use of xa_end(TMSUSPEND) at the end of a request and xa_start(TMRESUME) at the beginning of the next request in the same transaction, since an association must be resumed by the thread of control by which it was suspended.
 

A.2.5 The Standard Integration with C XA Resource Managers

• ResourceManager

A resource manager (logically) manages CosTransactions::Resource servants, or, using the XA vocabulary, transaction branches. ResourceManager is a distributed interface, which allows XA connections created in different ORB instances (and processes) to share the same CosTransactions::Resource/transaction branch.
 
• CurrentConnection

A CurrentConnection is a local object that gives access to the XA connection associated with the current XA thread-of-control.
 
• Connector

A local object used to create ResourceManager and CurrentConnection objects.

A.2.6 CurrentConnection

typedef short ThreadModel;
const ThreadModel PROCESS = 0;
const ThreadModel THREAD  = 1;

local interface CurrentConnection
{
    void
    start(                                   // xa_start(TMNOFLAGS) or xa_start(TMJOIN)
        in CosTransactions::Coordinator tx,
        in CosTransactions::otid_t      otid
     );

    void
    suspend(                                 // xa_end(TMSUSPEND)
        in CosTransactions::Coordinator tx,
        in CosTransactions::otid_t      otid
    );

    void resume(                             // xa_start(TMRESUME)
        in CosTransactions::Coordinator tx,
        in CosTransactions::otid_t      otid
    );

    void end(                                // xa_end(TMSUCCESS) or xa_end(TMFAIL)
        in CosTransactions::Coordinator tx,
        in CosTransactions::otid_t      otid,
        in boolean                      success
    );

   ThreadModel thread_model();
   long        rmid();

};

• start

start creates an association between an XA connection and a transaction branch.

In order to do some work within a distributed transaction with a given XA resource manager, the application needs to associate the resource manager's current connection with this transaction (or more precisely a transaction branch which represents this transaction in the resource manager), by calling CurrentConnection::start:

   // C++
   // assuming the OTS transaction is associated with the current thread

   CosTransactions::Control_var control = tx_current->get_control();
   CosTransactions::Coordinator_var tx = control->get_coordinator();
   CosTransactions::PropagationContext_var ctx = tx->get_txcontext();
   const CosTransactions::otid_t& otid = ctx->current.otid;
   current_connection->start(tx, otid);

The first time start is called with a given otid on one of the CurrentConnection objects associated with a ResourceManager, the ResourceManager creates a transaction branch, creates a CosTransactions::Resource persistent object representing this transaction branch and registers this object with the given transaction coordinator. The otid parameter is transformed into an XID and passed to xa_start(), unaltered.
Note: a compliant implementation does not need to create and register a CosTransaction::Resource object, as long as the external behavior is the same.

• suspend

suspend suspends an association between an XA connection and a transaction branch. It is merely a wrapper around xa_end(TMSUSPEND). The otid parameter is transformed into an XID and passed to xa_end(TMSUSPEND), unaltered. The tx parameter can be used to mark the transaction rollback-only when the implementation detects a fatal error.

• resume

resume resumes a previously suspended association between an XA connection and a transaction branch. It is merely a wrapper around xa_start(TMRESUME). The otid parameter is transformed into an XID and passed to xa_start(TMRESUME), unaltered. The tx parameter can be used to mark the transaction rollback-only when the implementation detects a fatal error.

• end

ends the association between an XA connection and a transaction branch

Once the application has finished using a connection, it needs to end the association with the transaction branch, for two reasons:

• ending the association releases the connection, and makes it available for other transaction branches. (suspend has actually the same effect).
• as long as any connection is associated with a transaction branch, the transaction cannot be committed (even the association is suspended). Some systems do not even allow to rollback a transaction branch while it is associated with any connection.
The otid parameter is transformed into an XID and passed to xa_end(), unaltered. The tx parameter can be used to mark the transaction rollback-only when the implementation detects a fatal error.

• thread_model

thread_model returns the XA thread-of-control mapping used by this CurrentConnection object.

When the thread model is PROCESS, xa_open() is called by or before the first start call; xa_close() is called during shutdown. When the thread model is THREAD, each thread calls xa_open() the first time (or before the first time) this thread executes CurrentConnection::start; xa_close() is called when this thread exits.
 

• rmid

rmid returns the rmid associated with this CurrentConnection object. The returned value is the same for any thread calling this operation.

In addition, the user may wish to alter the branch qualifier of the otid to either share the same transaction branch between different processes (tightly-coupled model) or use different transaction branches in processes using the same resource manager within the same distributed transaction (loosely-coupled model).

Figure 2 shows the components involved when the application creates a new association by calling start on a CurrentConnection object:

1. The application calls start on a CurrentConnection object.
2. The XA integration calls xa_start(TMNOFLAGS) to create a new transaction branch.
3. The XA integration creates a Resource object representing this branch, and registers this resource with the transaction coordinator.

A.2.7 Association State Diagram

When start, suspend, resume or end raises CORBA::INTERNAL with the minor code (TBD -- XAER_RMFAIL), the new state is "non existent".
When resume, suspend or end raises CORBA::TRANSACTION_ROLLEDBACK with the minor code (TBD -- XA_RB), the new state is "non existent".
When end raises CORBA::TRANSACTION_ROLLEDBACK with the minor code (TBD -- deferred rollback), the new state is "non existent".

For every other exceptions raised by start, suspend, resume and end, there is no state transition.

Note:
The PSS TransactionalSession interface has no resume operation: with PSS, when start is called on a suspended association, the association is resumed. Like PSS, JTA combines start and resume in a single method, Transaction.enlistResource().
Because of the CurrentConnection::resume operation, and implementation of the CurrentConnection local interface does not need to maintain information about the state of the underlying XA connection(s).
 

A.2.8 ResourceManager

interface BeforeCompletionCallback
{
     void
     before_completion(
         in CosTransactions::Coordinator tx,
         in CosTransactions::otid_t      otid,
         in boolean                      success
     );
};

interface ResourceManager
{
     unsigned long
     register_before_completion_callback(in BeforeCompletionCallback bcc);

     void
     unregister_before_completion_callback(in unsigned long key);
};

A Resource Manager object manages transaction branches. An application can register any number (up to 2^31 -1) of BeforeCompletionCallback objects with a resource manager, to get notified each time a non-preprared transaction branch is about to be prepared, committed-in-one-phase or rolled back.

The only operation on BeforeCompletionCallback, before_completion, accepts the following parameters:

• tx

if available, tx is the transaction coordinator used in the call to CurrentConnection::start that created this transaction branch; else tx is nil.

• otid

the otid_t parameter used in the call to CurrentConnection::start that created this transaction branch.

• success

a boolean parameter which is TRUE when the non-preparated transaction branch is about to be prepared or committed in one phase, and FALSE when the transaction branch is about to be rolled back.

A typical use of a BeforeCompletionCallback object is to end a suspended association in a single-threaded server, as shown on Figure 4.

An application uses the operation register_before_completion_callback to registers a BeforeCompletionCallback with a ResourceManager. register_before_completion_callback returns an unsigned long that the application uses to unregister a BeforeCompletionCallback object.

Note 1:  The primary advantage of BeforeCompletionCallback objects over CosTransactions::Synchronization objects is the number of  CORBA requests per transaction: three for a synchronization (registration, before_completion, after_completion) versus only one for a BeforeCompletionCallback object.

Note 2: When starting and ending an association for each request, there is no need for any BeforeCompletionCallback object.

Note 3: The interfaces between the CurrentConnection objects, the ResourceManager object and the Resource objects (if there is any) are not specified. The diagram above illustrates a possible implementation. Other implementations are possible: for example a Resource object could register itself with the Transaction Coordinator in its constructor.

A.2.9 Connector

The Connector local interface is defined in the XA module as follows:

native XASwitch;

local interface Connector
{
    ResourceManager
    create_resource_manager(
        in string                      resource_manager_name,
        in XASwitch                    xa_switch,
        in string                      open_string,
        in string                      close_string,
        in ThreadModel                 thread_model,
        in boolean                     automatic_association,
        in boolean                     dynamic_registration_optimization,
        out CurrentConnection          current_connection
    );

    CurrentConnection
    connect_to_resource_manager(
        in ResourceManager          rm,
        in XASwitch                 xa_switch,
        in string                   open_string,
        in string                   close_string,
        in ThreadModel              thread_model,
        in boolean                  automatic_association,
        in boolean                  dynamic_registration_optimization
     );
};
 

• native XASwitch

In C and C++, the native type XASwitch maps to an xa_switch_t: an 'in' XASwitch parameter is mapped to a const xa_switch_t& parameter in the corresponding C/C++ function. [3]
 
• create_resource_manager

The create_resource_manager operation creates (or recreates) a ResourceManager object, and a CurrentConnection local object.
The create_resource_manager parameters are:
• (in) resource_manager_name

A string identifying the resource manager. This string may be used by the implementation to generate a POA name unique within some scope.
• (in) xa_switch

A const reference to the xa_switch_t global variable that gives access to the XA resource manager.
• (in) open_string

The XA resource manager open string .
• (in) close_string

The XA resource manager close string.
• (in) thread_model

The thread model used by this XA resource manager.
• (in) automatic_association

When TRUE, each time the ORB from which the Connector was retrieved receives a transactional request, the XA integration calls start on the CurrentConnection created by this operation, using the coordinator and current otid retrieved from the PropagationContext. When the processing of the transactional request is complete, the XA integration calls end on the CurrentConnection created by this operation, using the same coordinator and otid. The success parameter is TRUE when the operation completed without raising a standard exception, and FALSE otherwise.
When FALSE, the XA integration is not involved during request processing.
• (in) dynamic_registration_optimization

When dynamic_registration_optimization is TRUE and the provided xa_switch supports dynamic registration, the XA integration may optimize the automatic_association processing described above by using XA dynamic registration: instead of calling start on the CurrentConnection when a transactional request is received, the XA integration relies on the ax_reg() call to create the association when needed.
When dynamic_registration_optimization is FALSE, the automatic_association processing is as described above.
• (out) current_connection

A new CurrentConnection local object connected to the ResourceManager created (or recreated) by this operation.
The ResourceManager object reference returned by create_resource_manager is persistent.
 
• connect_to_resource_manager

The connector_to_resource_manager operation creates a new CurrentConnection local object connected to an existing ResourceManager.
The connect_to_resource_manager parameters are:
 
•  (in) rm

An object reference of the ResourceManager to connect to. This ResourceManager needs to be provided by the same XA integration implementation: XA integration A cannot create a CurrentConnection connected to a ResourceManager provided by XA integration B.
• (in) xa_switch

A const reference to the xa_switch_t global variable that gives access to the XA resource manager.
• (in) open_string

The XA resource manager open string .
• (in) close_string

The XA resource manager close string.
• (in) thread_model

The thread model used by this XA resource manager.
• (in) automatic_association

When TRUE, each time the ORB from which the Connector was retrieved receives a transactional request, the XA integration calls start on the CurrentConnection created by this operation, using the coordinator and current otid retrieved from the PropagationContext. When the processing of the transactional request is complete, the XA integration calls end on the CurrentConnection created by this operation, using the same coordinator and otid. The success parameter is TRUE when the operation completed without raising a standard exception, and FALSE otherwise.
When FALSE, the XA integration is not involved during request processing.
• (in) dynamic_registration_optimization

When dynamic_registration_optimization is TRUE and the provided xa_switch supports dynamic registration, the XA integration may optimize the automatic_association processing described above by using XA dynamic registration: instead of calling start on the CurrentConnection when a transactional request is received, the XA integration relies on the ax_reg() call to create the association when needed.
When dynamic_registration_optimization is FALSE, the automatic_association processing is as described above.

A.2.10 Exceptions and Minor Codes

A.2.11 Comparison with the Java Transaction API (JTA)

XA	JTA
A xa_switch_t object	A transactional resource factory
An opened rmid	A XAResource object
xa_open_entry(char *, int, long)	no equivalent -- JTA does not standardize an API to open or close XA connections
xa_close_entry(char *, int, long)	no equivalent
xa_start_entry(XID *, int, long)	XAResource.start(Xid, int)
xa_end_entry(XID *, int, long)	XAResource.end(Xid, int)
xa_rollback_entry(XID *, int, long)	XAResource.rollback(Xid, int)
xa_prepare(XID *, int, long)	XAResource.prepare(Xid, int)
xa_commit(XID *, int, long)	XAResource.commit(Xid, int)
xa_recover(XID *, long, int, long)	XAResource.recover(int)
xa_forget(XID *, int, long)	XAResource.forget(Xid, int)
xa_complete(int *, int *, int, long);	no equivalent
no equivalent	XAResource.getTransactionTimeout()
no equivalent	XAResource.isSameRM(XAResource)
no equivalent	XAResource.setTransactionTimeout(int)

Transaction Service	JTA
Current	TransactionManager, UserTransaction
Synchronization	Synchronization
Control/Coordinator/Terminator	Transaction
Current::begin()	TransactionManager.begin(), UserTransaction.begin()
Current::commit()	TransactionManager.commit(), UserTransaction.commit()
Current::rollback()	TransactionManager.rollback(), UserTransaction.rollback()
Current::rollback_only()	TransactionManager.setRollbackOnly(), UserTransaction.setRollbackOnly()
Current::get_status()	TransactionManager.getStatus(), UserTransaction.getStatus()
Current::get_transaction_name()	TransactionManager.toString(), UserTransaction.toString()
Current::set_timeout()	TransactionManager.setTransactionTimeout()
Current::get_control()	TransactionManager.getTransaction()
Current::suspend()	TransactionManager.suspend()
Current::resume()	TransactionManager.resume()
Coordinator::get_status()	Transaction.getStatus()
Coordinator::is_same_transaction()	Transaction.equals() ?
Coordinator::hash_transaction()	Transaction.hashCode() ?
Coordinator::register_synchronization()	Transaction.registerSynchronization()
Coordinator::rollback_only()	Transaction.setRollbackOnly()
Terminator::commit()	Transaction.commit()
Terminator::rollback()	Transaction.rollback()
Other Coordinator operations	no equivalent

A.2.12 XA Module

#include <CosTransactions.idl>
#pragma prefix "omg.org"

module XA
{
    native XASwitch;

    typedef short ThreadModel;
    const ThreadModel PROCESS = 0;
    const ThreadModel THREAD  = 1;

    local interface CurrentConnection
    {
        void
        start(                                   // xa_start(TMNOFLAGS) or xa_start(TMJOIN)
             in CosTransactions::Coordinator tx,
             in CosTransactions::otid_t      otid
        );

        void
        suspend(                                 // xa_end(TMSUSPEND)
             in CosTransactions::Coordinator tx,
             in CosTransactions::otid_t      otid
        );

        void resume(                             // xa_start(TMRESUME)
             in CosTransactions::Coordinator tx,
             in CosTransactions::otid_t      otid
        );

        void end(                                // xa_end(TMSUCCESS) or xa_end(TMFAIL)
             in CosTransactions::Coordinator tx,
             in CosTransactions::otid_t      otid,
             in boolean                      success
        );

        ThreadModel thread_model();
        long        rmid();

    };

    interface BeforeCompletionCallback
    {
        void
        before_completion(
            in CosTransactions::Coordinator tx,
            in CosTransactions::otid_t      otid,
            in boolean                      success
        );
    };

    interface ResourceManager
    {
        unsigned long
        register_before_completion_callback(in BeforeCompletionCallback bcc);

        void
        unregister_before_completion_callback(in unsigned long key);
    };
 

    local interface Connector
    {
        ResourceManager
        create_resource_manager(
            in string                      resource_manager_name,
            in XASwitch                    xa_switch,
            in string                      open_string,
            in string                      close_string,
            in ThreadModel                 thread_model,
            in boolean                     automatic_association,
            in boolean                     dynamic_registration_optimization,
            out CurrentConnection          current_connection
        );

        CurrentConnection
        connect_to_resource_manager(
            in ResourceManager             rm,
            in XASwitch                    xa_switch,
            in string                      open_string,
            in string                      close_string,
            in ThreadModel                 thread_model,
            in boolean                     automatic_association,
            in boolean                     dynamic_registration_optimization
        );
    };
};

#endif  /*!_XA_IDL_*/
 
 

A.2.13 References

Footnotes:

[1] This integration with C XA resource managers is briefly described in Sun's Java Transaction Service specification (http://java.sun.com/products/jts), "3.3 Support for pre-JTA Resource Managers".

[2] 0 is reserved for OSI CCR naming. -1 means the XID is null.

[3] Mappings for other languages that interface with C, for example Ada and Java, could be defined as well.
For Java, it is expected that JTA-compliant XAResource implementations will be much more common than C xa_switch_t structs wrapped using JNI.