public interface ConfirmCompletedParticipant
This interface can be implemented by a BA participant in order to allow it to perform
its complete operation in two phases. This enables the participant to prepare
changes to persistent state and then commit them i) after the participant recovery
record has been written to disk but ii) before the coordinator is notified that the
participant has completed.
A participant completion participant is expected to prepare its changes before calling
completed. The BA implementation will call confirmCompleted after writing a recovery
record, ensuring compensation is possible before the changes are persisted. It will
not notify the coordinator that the participant has completed until after the callback
returns, ensuring that any notification received by the coordinator is valid.
A coordinator completion participant is expected to prepare its changes when its
completed method is called and then return. The BA implementation will call
confirmCompleted after writing a recovery record, ensuring compensation is possible
before the changes are persisted. It will not notify the coordinator that the
participant has completed until after the callback returns, ensuring that any
notification received by the coordinator is valid.
The associated participant recovery module must be able to detect uncommitted changes.
The logged recovery record should include some sort of identifier tying the changes to the
participant. If the recovery module identifies uncommitted changes with no associated
recovery record then a crash happened between prepare and completed and this means the
changes should be rolled back (presumed abort). If the recovery module identifies
uncommitted changes with an associated recovery record then a crash happened after completed
but before the confirmCompleted callback. The changes can be rolled forward and the participant
recreated. Alternatively, the changes can be rolled back and the participant record rejected.
If a recovery record is found with no uncommitted changes then the participant can be safely
recreated, allowing the recovery manager to resend a committed message.
It is possible that a completion operation may be initiated and then be cancelled part way through,
e.g. because a CANCEL message is received from the coordinator while writing the log record. in this
case the client will need to roll back any uncommitted changes. A boolean flag argument to the
confirmCompleted method is used to distinguish this case. If the flag is supplied as true then
changes should be committed. If it is supplied as false then changes should be rolled back.