Chapter 20. Participants
20.1. Overview
The participant is the entity that performs the work pertaining to transaction management on behalf of the business services involved in an application. The Web service (in the example code, a theater booking system) contains some business logic to reserve a seat and inquire about availability, but it needs to be supported by something that maintains information in a durable manner. Typically this is a database, but it could be a file system, NVRAM, or other storage mechanism.
Although the service may talk to the back-end database directly, it cannot commit or undo any changes, since committing and rolling back are ultimately under the control of a transaction. For the transaction to exercise this control, it must communicate with the database. In XTS, participant does this communication, as shown in Figure 20.1, “Transactions, Participants, and Back-End Transaction Control”.
Figure 20.1. Transactions, Participants, and Back-End Transaction Control
20.1.1. Atomic Transaction
All Atomic Transaction participants are instances of the Section 20.1.1.1, “Durable2PCParticipant” or Section 20.1.1.2, “Volatile2PCParticipant”.
20.1.1.1. Durable2PCParticipant
A Durable2PCParticipant supports the WS-Atomic Transaction Durable2PC protocol with the signatures listed in Durable2PCParticipant Signatures, as per the
com.arjuna.wst11.Durable2Participant interface.
Durable2PCParticipant Signatures
prepare- The participant should perform any work necessary, so that it can either commit or roll back the work performed by the Web service under the scope of the transaction. The implementation is free to do whatever it needs to in order to fulfill the implicit contract between it and the coordinator.The participant indicates whether it can
prepareby returning an instance of thecom.arjuna.wst11.Vote, with one of three values.ReadOnlyindicates that the participant does not need to be informed of the transaction outcome, because it did not update any state information.Preparedindicates that the participant is ready to commit or roll back, depending on the final transaction outcome. Sufficient state updates have been made persistent to accomplish this.Abortedindicates that the participant has aborted and the transaction should also attempt to do so.
commit- The participant should make its work permanent. How it accomplishes this depends upon its implementation. For instance, in the theater example, the reservation of the ticket is committed. If commit processing cannot complete, the participant should throw a
SystemExceptionerror, potentially leading to a heuristic outcome for the transaction. rollback- The participant should undo its work. If rollback processing cannot complete, the participant should throw a
SystemExceptionerror, potentially leading to a heuristic outcome for the transaction. unknown- This method has been deprecated and is slated to be removed from XTS in the future.
error- In rare cases when recovering from a system crash, it may be impossible to complete or roll back a previously prepared participant, causing the
erroroperation to be invoked.
20.1.1.2. Volatile2PCParticipant
This participant supports the WS-Atomic Transaction Volatile2PC protocol with the signatures listed in Volatile2PCParticipant Signatures, as per the
com.arjuna.wst11.Volatile2Participant interface.
Volatile2PCParticipant Signatures
prepare- The participant should perform any work necessary to flush any volatile data created by the Web service under the scope of the transaction, to the system store. The implementation is free to do whatever it needs to in order to fulfill the implicit contract between it and the coordinator.The participant indicates whether it can
prepareby returning an instance of thecom.arjuna.wst11.Vote, with one of three values.ReadOnlyindicates that the participant does not need to be informed of the transaction outcome, because it did not change any state information during the life of the transaction.Preparedindicates that the participant wants to be notified of the final transaction outcome via a call tocommitorrollback.Abortedindicates that the participant has aborted and the transaction should also attempt to do so.
- commit
- The participant should perform any cleanup activities required, in response to a successful transaction commit. These cleanup activities depend upon its implementation. For instance, it may flush cached backup copies of data modified during the transaction. In the unlikely event that commit processing cannot complete, the participant should throw a
SystemExceptionerror. This will not affect the outcome of the transaction but will cause an error to be logged. This method may not be called if a crash occurs during commit processing. - rollback
- The participant should perform any cleanup activities required, in response to a transaction abort. In the unlikely event that rollback processing cannot complete, the participant should throw a
SystemExceptionerror. This will not affect the outcome of the transaction but will cause an error to be logged. This method may not be called if a crash occurs during commit processing. - unknown
- This method is deprecated and will be removed in a future release of XTS.
- error
- This method should never be called, since volatile participants are not involved in recovery processing.
20.1.2. Business Activity
All Business Activity participants are instances one or the other of the interfaces described in Section 20.1.2.1, “BusinessAgreementWithParticipantCompletion” or Section 20.1.2.2, “BusinessAgreementWithCoordinatorCompletion” interface.
20.1.2.1. BusinessAgreementWithParticipantCompletion
The
BusinessAgreementWithParticipantCompletion interface supports the WS-Transactions BusinessAgreementWithParticipantCompletion protocol with the signatures listed in BusinessAgreementWithParticipantCompletion Signatures, as per interface com.arjuna.wst11.BusinessAgreementWithParticipantCompletionParticipant.
BusinessAgreementWithParticipantCompletion Signatures
close- The transaction has completed successfully. The participant has previously informed the coordinator that it was ready to complete.
cancel- The transaction has canceled, and the participant should undo any work. The participant cannot have informed the coordinator that it has completed.
compensate- The transaction has canceled. The participant previously informed the coordinator that it had finished work but could compensate later if required, and it is now requested to do so. If compensation cannot be performed, the participant should throw a
FaultedExceptionerror, potentially leading to a heuristic outcome for the transaction. If compensation processing cannot complete because of a transient condition then the participant should throw aSystemExceptionerror, in which case the compensation action may be retried or the transaction may finish with a heuristic outcome. status- Return the status of the participant.
unknown- This method is deprecated and will be removed a future XTS release.
- error
- In rare cases when recovering from a system crash, it may be impossible to compensate a previously-completed participant. In such cases the
erroroperation is invoked.
20.1.2.2. BusinessAgreementWithCoordinatorCompletion
The BusinessAgreementWithCoordinatorCompletion participant supports the WS-Transactions
BusinessAgreementWithCoordinatorCompletion protocol with the signatures listed in BusinessAgreementWithCoordinatorCompletion Signatures, as per the com.arjuna.wst11.BusinessAgreementWithCoordinatorCompletionParticipant interface.
BusinessAgreementWithCoordinatorCompletion Signatures
close- The transaction completed successfully. The participant previously informed the coordinator that it was ready to complete.
cancel- The transaction canceled, and the participant should undo any work.
compensate- The transaction canceled. The participant previously informed the coordinator that it had finished work but could compensate later if required, and it is now requested to do so. In the unlikely event that compensation cannot be performed the participant should throw a
FaultedExceptionerror, potentially leading to a heuristic outcome for the transaction. If compensation processing cannot complete because of a transient condition, the participant should throw aSystemExceptionerror, in which case the compensation action may be retried or the transaction may finish with a heuristic outcome. complete- The coordinator is informing the participant all work it needs to do within the scope of this business activity has been completed and that it should make permanent any provisional changes it has made.
status- Returns the status of the participant.
unknown- This method is deprecated and will be removed in a future release of XTS.
error- In rare cases when recovering from a system crash, it may be impossible to compensate a previously completed participant. In such cases, the
errormethod is invoked.
20.1.2.3. BAParticipantManager
In order for the Business Activity protocol to work correctly, the participants must be able to autonomously notify the coordinator about changes in their status. Unlike the Atomic Transaction protocol, where all interactions between the coordinator and participants are instigated by the coordinator when the transaction terminates, the BAParticipantManager interaction pattern requires the participant to be able to talk to the coordinator at any time during the lifetime of the business activity.
Whenever a participant is registered with a business activity, it receives a handle on the coordinator. This handle is an instance of interface com.arjuna.wst11.BAParticipantManager with the methods listed in BAParticipantManager Methods.
BAParticipantManager Methods
exit- The participant uses the method
exitto inform the coordinator that it has left the activity. It will not be informed when and how the business activity terminates. This method may only be invoked while the participant is in theactivestate (or thecompletingstate, in the case of a participant registered for theParticipantCompletionprotocol). If it is called when the participant is in any other state, aWrongStateExceptionerror is thrown. Anexitdoes not stop the activity as a whole from subsequently being closed or canceled/compensated, but only ensures that the exited participant is no longer involved in completion, close or compensation of the activity. completed- The participant has completed its work, but wishes to continue in the business activity, so that it will eventually be informed when, and how, the activity terminates. The participant may later be asked to compensate for the work it has done or learn that the activity has been closed.
fault- The participant encountered an error during normal activation and has done whatever it can to compensate the activity. The
faultmethod places the business activity into a mandatorycancel-onlymode. The faulted participant is no longer involved in completion, close or compensation of the activity.
