JBoss.orgCommunity Documentation
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.
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
Indicates that the participant can can prepare if the coordinator requests it. Nothing has been committed, because the participant does not know the final outcome of the transaction.
The participant cannot prepare, and has rolled back. The participant should not expect to get a second phase message.
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 7.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();
}
}
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
Indicates whether the contents are valid.
Can be used to compare two instances for equality.
The corresponding participant interfaces used in the 1.0 protocol implementation are located in package com.arjuna.wst.
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
Used to begin a new transaction and associate it with the invoking thread.
Parameters
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
WrongStateExceptionA transaction is already associated with the thread.
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
UnknownTransactionExceptionNo transaction is associated with the invoking thread.
TransactionRolledBackExceptionThe transaction was rolled back either because of a timeout or because a participant was unable to commit.
Terminates the transaction. Upon completion, the rollback method disassociates the
transaction from the current leaving it unassociated with any transactions.
Exceptions
UnknownTransactionExceptionNo transaction is associated with the invoking thread.
Call the getUserTransaction method to obtain a Section 7.1.3, “UserTransaction”
instance from a UserTransactionFactory.
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.
suspendDissociates 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
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.
enlistForVolitaleTwoPhaseEnroll 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
An implementation of interface Volatile2PCParticipant whose prepare, commit and abort methods are called when the corresponding coordinator message is received.
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
No transaction is associated with the invoking thread.
WrongStateExceptionThe transaction is not in a state that allows participants to be enrolled. For instance, it may be in the process of terminating.
enlistForDurableTwoPhaseEnroll 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
No transaction is associated with the invoking thread.
WrongStateExceptionThe transaction is not in a state that allows participants to be enrolled. For instance, it may be in the process of terminating.
Use the getTransactionManager method to obtain a Section 7.1.5, “TransactionManager”
from a TransactionManagerFactory.
Previous implementations of XTS locate the Business Activity Protocol classes in the com.arjuna.mw.wst package. In the current implementation, these classes are located in the com.arjuna.mw.wst11 package.
com.arjuna.wst11.UserBusinessActivity is the class that most clients employ. A client begins a
new business activity by first obtaining a UserBusinessActivity from the
UserBusinessActivityFactory. This class isolates them from the underlying protocol-specific
aspects of the XTS implementation. A UserBusinessActivity does not represent a specific business activity. Instead,
it provides access to an implicit per-thread activity. Therefore, all of the
UserBusinessActivity methods implicitly act on the current thread of control.
Methods
beginBegins a new activity, associating it with the invoking thread.
Parameters
The interval, in milliseconds, after which an activity times out. Optional.
Exceptions
WrongStateExceptionThe thread is already associated with a business activity.
closeFirst, all Coordinator Completion participants enlisted in the activity are requested to complete the activity. Next all participants, whether they enlisted for Coordinator or Participant Completion, are requested to close the activity. If any of the Coordinator Completion participants fails to complete at the first stage then all completed participants are asked to compensate the activity while any remaining uncompleted participants are requested to cancel the activity.
Exceptions
No activity is associated with the invoking thread.
The activity has been cancelled because one of the Coordinator Completion participants failed to complete. This exception may also thrown if one of the Participant Completion participants has not completed before the client calls close.
Terminates the business activity. All Participant Completion participants enlisted in the activity which have already completed are requested to compensate the activity. All uncompleted Participant Completion participants and all Coordinator Completion participants are requested to cancel the activity.
Exceptions
UnknownTransactionExceptionNo activity is associated with the invoking thread. Any participants that previous completed are directed to compensate their work.
Use the getuserbusinessActivity method to obtain a Section 7.2.2, “UserBusinessActivity” instance from a userBusinessActivityFactory.
com.arjuna.mw.wst11.BusinessActivityManager is the class that web services typically
employ. Defines how a web service interacts with the underlying business activity service implementation. A
BusinessActivityManager does not represent a specific activity. Instead, it provides access to
an implicit per-thread activity.
Methods
currentTransaction
Returns the TxContext for the current business activity, or NULL if
there is no TxContext. The returned value can be used to enable multiple threads to
execute within the scope of the same business activity. Calling the currenTransaction
method does not dissociate the current thread from its activity.
suspend
Dissociates a thread from any current business activity, so that it can perform work not associated with a
specific activity. The suspend method returns a TxContext
instance, which is a handle on the activity. The thread is then no longer associated with any activity.
resume
Associates or re-associates a thread with a business activity, using its
TxContext. Before associating or re-associating the thread, it is disassociated from
any business activity with which it is currently associated. If the TxContext is
NULL, the thread is disassociated with all business activities, as though the
suspend method were called.
Parameters
A TxContext instance as returned by suspend, identifying the transaction to be
resumed.
Exceptions
UnknownTransactionException
The business activity to which the TxContext refers is invalid in the scope of the
invoking thread.
enlistForBusinessAgreementWithParticipantCompletion
Enroll the specified participant with current business activity, causing it to participate in the
BusinessAgreementWithParticipantCompletion protocol. A unique identifier for the
participant is also required.
The return value is an instance of BAParticipantManager which can be used to notify the coordinator of changes in the participant state. In particular, since the participant is enlisted for the Participant Completion protcol it is expected to call the completed method of this returned instance when it has completed all the work it expects to do in this activity and has made all its changes permanent. Alternatively, if the participant does not need to perform any compensation actions should some other participant fail it can leave the activity by calling the exit method of the returned BAParticipantManager instance.
Parameters
An implementation of interface
BusinessAgreementWithParticipantCompletionParticipant whose
close, cancel, and compensate
methods are called when the corresponding coordinator message is received.
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
No transaction is associated with the invoking thread.
The transaction is not in a state where new participants may be enrolled, as when it is terminating.
enlistForBusinessAgreementWithCoordinatorCompletion
Enroll the specified participant with current activity, causing it to participate in the
BusinessAgreementWithCoordinatorCompletion protocol. A unique identifier for the
participant is also required.
The return value is an instance of BAParticipantManager which can be used to
notify the coordinator of changes in the participant state. Note that in this case it is an error to call the
completed method of this returned instance. With the Coordinator Completion protocol
the participant is expected to wait until its completed method is called before it
makes all its changes permanent. Alternatively, if the participant determiens that it has no changes to make,
it can leave the activity by calling the exit method of the returned
BAParticipantManager instance.
Parameters
An implementation of interface BusinessAgreementWithCoordinatorCompletionParticipant whose completed, close, cancel and compensate methods are called when the corresponding coordinator message is received.
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
No transaction is associated with the invoking thread.
The transaction is not in a state where new participants may be enrolled, as when it is terminating.
Use the getBusinessActivityManager method to obtain a Section 7.2.4, “BusinessActivityManager” instance from a BusinessActivityManagerFactory.