The Mulgara JTA Interface¶

The Existing Interface¶

Mulgara originally provided two transactional interfaces, implicit and explicit.
This mediated via the Session object, and the method used to select between them
is called setAutoCommit(). When auto-commit is true, all operations on the
Session use the implicit interface. Setting auto-commit false initiates an
explicit (or user-demarcated) transaction. Irrespective of any commit/rollback,
once auto-commit is false all transactions are user-demarcated until it is set
to true again. While auto-commit is true every operation on the Session will
initiate a new transaction which will be finalised (either commit or rollback)
before the operation returns (except for queries, which are finalized when the
answer is closed - see below).

All transactions initiated via the explicit interface are read-write, whereas
only those operations that perform updates initiate implicit read-write
transactions. Naturally both interfaces use the same underlying transactional
mechanisms within Mulgara, including a single shared write-lock that only
permits a single read-write transaction to proceed at a time.

Explicit transactions are controlled via three methods on the Session interface.

• Session::setAutoCommit() allows the developer to select which transactional
  interface to use, and to initiate a transaction (this does conflate two
  concepts, but to date that has not proven to be a problem).
• Session::commit() commits the current transaction an initiates a new
  transaction without dropping the write-lock.
• Session::rollback() rollbacks the current transaction an initiates a new
  transaction without dropping the write-lock.

There are two other ways for a user-demarcated transaction to be terminated.

• If an exception is thrown from an operation on the session, or on a query
  result associated with the transaction, the transaction is rolled back and
  the write-lock is dropped.
• If the transaction timeout expires then the transaction is rolled back and
  the write-lock is dropped.

In both cases the session remains in explicit transaction control; however, as
all operations start by attempting to activate the transaction, any attempt to
perform any operation other than Session::setAutoCommit(true) or
Session::rollback on the session results in an exception (the difference between
the two is that rollback will acquire the write-lock before returning).

To ensure full transaction isolation/serialisability each answer returned from a
query holds a reference to the transaction/phase it was performed against. This
means that the results of queries performed within an implicit transaction
remain valid until such a time as either the result or the originating session
itself is closed. However due to this reliance on the originating transaction,
query results obtained from an explicit transaction do not out live it, and are
invalidated as soon as the transaction is terminated.

This approach greatly simplifies the normal case of an application that is
performing an atomic insert, delete, or query. In this case the application
developer can ignore transactions altogether and the implict transaction control
will 'do the right thing'. For more complex applications, the explicit
transation controls available on session are sufficient for almost all uses of
mulgara as a standalone store.

Motivation for a new interface¶

There are however two gaps in the original transaction interface.

The first is that it is impossible to perform a series of transactionally
consistant queries except by grouping them into a single call to
Session::query(List); or by first initiating an explicit transaction in order to
obtain the write-lock, preventing any potentially inconsistent updates.
Naturally the former is not always possible, and the latter is undesirable,
especially as mulgara is a multiversion datastore and it therefore should be
possible to obtain a handle to a given version (phase) and run multiple queries
against it.

The second is that the interface provides no access to the two-phase commit
protocol used by mulgara internally. This isn't a problem when using mulgara as
a standalone server, however it does make it impossible to incorporate mulgara
in a distributed transaction with other stores or databases safely.

The Java standard for providing access to a two-phase commit protocol is the
"Java Transaction API" (JTA). A java transaction (and slight simplification) of
the Object Management Group (OMG)'s "Transaction Service Specification" (OTS), which
is the transaction management specification for CORBA. The OTS is itself an
object-oriented mapping of the "DTP/XA Specification" (XA-spec)from X/Open (now The Open
Group). The relevant versions of the various specifications are:

• JTA : Java Transaction API (JTA), Version 1.1, 2002
• OTS : Transaction Service Specification, Version 1.2, 2001
• XA-Spec : Distributed Transaction Processing: The XA Specification,
  XO/CAE/91/300, 1991
  The XA-Spec relies for context on the "DTP/Reference Model" (XA-model), 1991;
  although the mulgara JTA implementation was guided with reference to the more
  recent version 3, 1996.
• XA-model : Distribute Transaction Processing: Reference Model Version 3,
  G504, 1996

While the primary requirement for JTA support is the need to provide a two-phase
commit interface, the opportunity was also taken to provide explicit control of
read-only transactions which solves the problem of supporting multiple
consistent reads as discussed above.

Limitations of the JTA interface¶

The write-lock is not a consequence of the existing interface, but rather a
property of the underlying mulgara XA1 store implementation. As a result the
use of JTA does not affect the serialisation of write transactions. It remains
the case that any attempt to initiate a write-transaction will block until such
a time as the write-lock becomes available. The current JTA implementation
within mulgara does not provide any timeout on this wait, so application
developers should be aware that calls to start a mulgara transaction may block
for an arbitary time.

On restart mulgara automatically and releases (garbage collects) any phases
(versions) other than the most recently committed. This startup protocol is
done without any journal reruns resulting in an instantaneous restart. On the
other hand this protocol does mean that mulgara discards any prepared
transactions on restart, effectively performing a heuristic rollback. As
mulgara makes no distinction between prepared and unprepared transactions on
restart, mulgara does not persist the prepared status of a transaction. This
means that the mulgara JTA implementation cannot participate in the JTA recovery
protocol. As a result on restart users should consider all transactions to be
Heuristically Completed (state S5 in XA-spec 6.3), with status XA_HEURRB in the
case of a restart prior to a call to commit, and status XA_HEURHAZ on a restart
during a commit call. It is apropos here to recall that XA_HEURMIX is only
possible if an update operation is performed on an external datastore via a
resolver (at the moment only lucene supports this); atomicity is guaranteed
with respect to the mulgara rdf-store itself.

The JTA interface is a Java interface that is expected to operate transparently
over a network. As with Mulgara's session interface, the JTA interface uses RMI
to provide network transparency. This should not be a problem as the RMI based
JTA implementation can only be obtained via the RMI based session
implementation, however any interruption to RMI operation will affect
transaction control.

Accessing the JTA interface¶

The fundamental requirement for supporting JTA is providing a way of obtaining
an XAResource. JTA requires that each XAResource be associated with a "Resource
Manager Instance". When mapping this to Mulgara, and taking into consideration
the code in the JTA-spec (3.4.9), the Session object was identified as best
fitting JTA's use of the term RM instance. The JTA interface therefore adds two
new methods to Session:

  Session::getXAResource()
  Session::getReadOnlyXAResource()

Both return an XAResource object, associated with the session. All transactions
initiated via a call to XAResource::start() will be read-write or read-only
depending on if the XAResource was obtained via getXAResource or
getReadOnlyXAResource respectively.

The preexisting interface manages the transaction state transitions internally,
as compared to the JTA interface which exposes these transitions to the external
control of an external transaction manager. Consequently within mulgara
transactions created via the JTA interface are referred to as "external
transactions", those by the older implicit and explicit interface as "internal
transactions". While JTA 3.4.7 encourages supporting both Local (internal) and
Global (external) transactions through the same "connection", supporting this
would drastically increase the number of operation combinations that would need
to be tested to ensure confidence in the transaction logic. Therefore the
current mulgara JTA implementation does not support the use of both internal and
external transactions on the same session. To select which interface is active
on a given session the developer should simply use it. The first use of a given
interface (internal or external) disables the other. This ensures full
backwards compatibility with existing code while simplifying the process of
testing and building confidence in the new interface.

Using the JTA interface¶

It is worth mentioning that none of the underlying transactional machinery has
changed, consequently all Answer objects still reference their originating
transaction, and all transactions ultimately must map to a specific phase on the
store. As a result it is important to keep in mind that once a JTA mediated
transaction is terminated via the XAResource, the reference to the phase is
released and all outstanding Answer objects are invalidated. In this the JTA
interface works very similarly to the explict internal interface.

JTA also recommends supporting multiple outstanding transactions on a single RM
instance. The Mulgara JTA implementation provides full support for this,
however developers attempting to use this functionality must be careful to
observe the restrictions imposed by the JTA standard. JTA provides support for
concurrent transactions on a single resource adaptor via calls to
XAResource::suspend() and XAResource::resume(). These transition the specified
transaction from Associated to Suspended states (see JTA-spec 3.4.4, although
XA-spec Ch.6 is more complete). JTA requires (as does the mulgara
implementation) that at most one transaction be associated with the
transactional resource at any given time.

The following example of concurrent use of JTA transactions on a single session
is excerpted from org.mulgara.resolver.!JotmTransactionStandaloneUnitTest.java

{
  txManager.begin();

  Session session = sessionFactory.newSession();
  XAResource roResource = session.getReadOnlyXAResource();
  XAResource rwResource = session.getXAResource();

  /*
*** Note: JTA requires that you initiate the global transaction (via mgr::begin()
*** above), before you enlist a resource.
*** The call to enlistResource for an XAResource for the first time in a given
*** global transaction will cause the Transaction Manager to call xa::start() on
*** the XAResource, initiating a mulgara transaction.
*** As we are using an XAResource obtained via xa::getXAResource(), this
*** transaction will be a read-write transaction - note this does mean that
*** this call could block waiting on the write-lock availability.
   */
  txManager.getTransaction().enlistResource(rwResource);
  session.createModel(...);
  Transaction tx1 = txManager.suspend();
  /*
*** Note: Without the call to mgr::suspend, subsequent calls to enlistResource will
*** detect that there is an existing transaction and result in a call to
*** xa::start(TM_JOIN), which is either a no-op (if a read-only 'joins' a
*** read-write transaction) or an exception (if a read-write attempts to 'join'
*** a read-only transaction).
*** With the call to mgr::suspend() the transaction is temporarally
*** disassociated from this thread, and from this session.  A Consequent call to
*** mgr::begin() will result in the transaction manager initiating a new
*** transaction, and an ensuing call to xa::enlistResource a new mulgara
*** transaction.
*** It is important to realise that all operations on a session object are
*** evaluated with respect to the currently associated transaction.  If all
*** transactions are suspended or completed then operations will result in an
*** exception.
   */

  txManager.begin();
  txManager.getTransaction().enlistResource(roResource);
  Answer answer = session.query(new Query(...));
  Transaction tx2 = txManager.suspend();

  /*
*** Answers carry their own association with the mulgara transaction, so the
*** transaction does not need to be reassociated with the originating session
*** to use an Answer object.  This does run counter to assumptions of the JTA
*** specification, however as the JTA specification assumes a traditional
*** relational database, many of the capabilities of multiversion datastores
*** (such as mulgara) flexibility is required in adapting multiversion
*** transactions to JTA.
   */
  answer.beforeFirst();
  while (answer.next()) {
    ...
  }

  txManager.resume(tx1);
  session.insert(...);
  tx1 = txManager.suspend();
  answer.close();
  txManager.resume(tx1);
  txManager.commit();

  /*
*** Note the suport for user-demarcated concurrent read-only transactions.
   */
  txManager.begin();
  txManager.getTransaction().enlistResource(roResource);
  Answer answer2 = session.query(new Query(...));
  Transaction tx3 = txManager.suspend();

  // use answer2.
  answer2.close();

  /*
*** Note the call to tx3.commit() is performed on a suspended transaction.  As
*** tx3 is a handle to the transaction it does not need to be reassociated with
*** the current thread as is required if it is going to be committed via the
*** transaction manager.  This flexibility is mandated by JTA.
   */
  txManager.begin();
  txManager.getTransaction().enlistResource(rwResource);
  session.removeModel(...);
  txManager.commit();
  txManager.resume(tx2);
  txManager.commit();
  tx3.commit();
  session.close();
}