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
rollbackmethod 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
TxContextfor the current transaction, or null if there is no context. Use thecurrentTransactionmethod 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 thecurrentTransactionmethod 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
suspendmethod returns aTxContextinstance, 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 theTxContextis null, then the thread is associated with no transaction. In this way, the result is the same as if thesuspendmethod 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
TxContextis 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.
