Chapter 21. The XTS API

This chapter discusses the XTS API. You can use this information to write client and server applications which consume transactional Web Services and coordinate back-end systems.

21.1. API for the Atomic Transaction Protocol

21.1.1. Vote

During the two-phase commit protocol, a participant is asked to vote on whether it can prepare to confirm the work that it controls. It must return an instance of one of the subtypes of com.arjuna.wst11.Vote listed in Subclasses of com.arjuna.wst11.Vote.

Subclasses of com.arjuna.wst11.Vote

Prepared
Indicates that the participant can prepare if the coordinator requests it. Nothing has been committed, because the participant does not know the final outcome of the transaction.
Aborted
The participant cannot prepare, and has rolled back. The participant should not expect to get a second phase message.
ReadOnly
The participant has not made any changes to state, and it does not need to know the final outcome of the transaction. Essentially the participant is resigning from the transaction.

Example 21.1. Example Implementation of 2PC Participant's prepare Method

public Vote prepare () throws WrongStateException, SystemException
{
  // Some participant logic here

  if(/* some condition based on the outcome of the business logic */)
  {
    // Vote to confirm
    return new com.arjuna.wst.Prepared();
  }
  else if(/*another condition based on the outcome of the business logic*/)
  {
    // Resign
    return new com.arjuna.wst.ReadOnly();
  }
  else
  {
    // Vote to cancel
    return new com.arjuna.wst.Aborted();
  }
}

21.1.2. TXContext

com.arjuna.mw.wst11.TxContext is an opaque representation of a transaction context. It returns one of two possible values, as listed in TxContext Return Values.

TxContext Return Values

valid
Indicates whether the contents are valid.
equals
Can be used to compare two instances for equality.

Note

The corresponding participant interfaces used in the 1.0 protocol implementation are located in package com.arjuna.wst.

21.1.3. UserTransaction

com.arjuna.mw.wst11.UserTransaction is the class that clients typically employ. Before a client can begin a new atomic transaction, it must first obtain a UserTransaction from the UserTransactionFactory. This class isolates the user from the underlying protocol-specific aspects of the XTS implementation. A UserTransaction does not represent a specific transaction. Instead, it provides access to an implicit per-thread transaction context, similar to the UserTransaction in the JTA specification. All of the UserTransaction methods implicitly act on the current thread of control.

userTransaction Methods

begin
Used to begin a new transaction and associate it with the invoking thread.

Parameters

timeout
This optional parameter, measured in milliseconds, specifies a time interval after which the newly created transaction may be automatically rolled back by the coordinator

Exceptions

WrongStateException
A transaction is already associated with the thread.
commit
Volatile2PC and Durable2PC participants enrolled in the transaction are requested first to prepare and then to commit their changes. If any of the participants fails to prepare in the first phase then all other participants are requested to abort.

Exceptions

UnknownTransactionException
No transaction is associated with the invoking thread.
TransactionRolledBackException
The transaction was rolled back either because of a timeout or because a participant was unable to commit.
rollback
Terminates the transaction. Upon completion, the rollback method disassociates the transaction from the current leaving it unassociated with any transactions.

Exceptions

UnknownTransactionException
No transaction is associated with the invoking thread.

21.1.4. UserTransactionFactory

Call the getUserTransaction method to obtain a Section 21.1.3, “UserTransaction” instance from a UserTransactionFactory.

21.1.5. TransactionManager

Defines the interaction between a transactional web service and the underlying transaction service implementation. A TransactionManager does not represent a specific transaction. Instead, it provides access to an implicit per-thread transaction context.

Methods

currentTransaction
Returns a TxContext for the current transaction, or null if there is no context. Use the currentTransaction method to determine whether a web service has been invoked from within an existing transaction. You can also use the returned value to enable multiple threads to execute within the scope of the same transaction. Calling the currentTransaction method does not disassociate the current thread from the transaction.
suspend
Dissociates a thread from any transaction. This enables a thread to do work that is not associated with a specific transaction.
The suspend method returns a TxContext instance, which is a handle on the transaction.
resume
Associates or re-associates a thread with a transaction, using its TxContext. Prior to association or re-association, the thread is disassociated from any transaction with which it may be currently associated. If the TxContext is null, then the thread is associated with no transaction. In this way, the result is the same as if the suspend method were used instead.

Parameters

txContext
A TxContext instance as return by suspend, identifying the transaction to be resumed.

Exceptions

UnknownTransactionException
The transaction referred to by the TxContext is invalid in the scope of the invoking thread.
enlistForVolitaleTwoPhase
Enroll the specified participant with the current transaction, causing it to participate in the Volatile2PC protocol. You must pass a unique identifier for the participant.

Parameters

participant
An implementation of interface Volatile2PCParticipant whose prepare, commit and abort methods are called when the corresponding coordinator message is received.
id
A unique identifier for the participant. The value of this String should differ for each enlisted participant. It should also be possible for a given identifier to determine that the participant belongs to the enlisting web service rather than some other web service deployed to the same container.

Exceptions

UnknownTransactionException
No transaction is associated with the invoking thread.
WrongStateException
The transaction is not in a state that allows participants to be enrolled. For instance, it may be in the process of terminating.
enlistForDurableTwoPhase
Enroll the specified participant with the current transaction, causing it to participate in the Durable2PC protocol. You must pass a unique identifier for the participant.

Exceptions

UnknownTransactionException
No transaction is associated with the invoking thread.
WrongStateException
The transaction is not in a state that allows participants to be enrolled. For instance, it may be in the process of terminating.

21.1.6. TransactionManagerFactory

Use the getTransactionManager method to obtain a Section 21.1.5, “TransactionManager” from a TransactionManagerFactory.