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”.
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 prepare by returning an instance of the com.arjuna.wst11.Vote, with one of three values.
  • ReadOnly indicates that the participant does not need to be informed of the transaction outcome, because it did not update any state information.
  • Prepared indicates 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.
  • Aborted indicates 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 SystemException error, 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 SystemException error, 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 error operation 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 prepare by returning an instance of the com.arjuna.wst11.Vote, with one of three values.
  • ReadOnly indicates 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.
  • Prepared indicates that the participant wants to be notified of the final transaction outcome via a call to commit or rollback.
  • Aborted indicates 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 SystemException error. 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 SystemException error. 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 FaultedException error, potentially leading to a heuristic outcome for the transaction. If compensation processing cannot complete because of a transient condition then the participant should throw a SystemException error, 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 error operation 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 FaultedException error, potentially leading to a heuristic outcome for the transaction. If compensation processing cannot complete because of a transient condition, the participant should throw a SystemException error, 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 error method 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 exit to 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 the active state (or the completing state, in the case of a participant registered for the ParticipantCompletion protocol). If it is called when the participant is in any other state, a WrongStateException error is thrown. An exit does 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 fault method places the business activity into a mandatory cancel-only mode. The faulted participant is no longer involved in completion, close or compensation of the activity.