Chapter 20. Participants

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.

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.

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.

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.

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.