Chapter 23. Participant Crash Recovery
Procedure 23.1. Presumed Abort Policy
- If the coordinator crashes, it can assume that any transaction it does not know about is invalid, and reject a participant request which refers to such a transaction.
- If the participant crashes, it can forget any provisional changes it has made, and reject any request from the coordinator service to prepare a transaction or complete a business activity.
- WS-AT Transaction
- The transaction needs to commit all provisional changes or roll them all back to the state before the transaction started.
- WS-Business Activity Transaction
- All participants need to close the activity or cancel the activity, and run any required compensating actions.
23.1. WS-AT Recovery
23.1.1. WS-AT Coordinator Crash Recovery
prepare
message and have responded with a prepared
message, the coordinator writes a log record storing each participant's details, indicating that the transaction is ready to complete. If the coordinator service crashes after this point has been reached, completion of the two-phase commit protocol is still guaranteed, by reading the log file after reboot and sending a commit
message to each participant. Once all participants have responded to the commit
with a committed
message, the coordinator can safely delete the log entry.
prepared
messages returned by the participants imply that they are ready to commit their provisional changes and make them permanent, this type of recovery is safe. Additionally, the coordinator does not need to account for any commit messages which may have been sent before the crash, or resend messages if it crashes several times. The XTS participant implementation is resilient to redelivery of the commit
messages. If the participant has implemented the recovery functions described in Section 23.1.2.1, “WS-AT Participant Crash Recovery APIs”, the coordinator can guarantee delivery of commit
messages if both it crashes, and one or more of the participant service hosts also crash, at the same time.
prepare
phase completes, the presumed abort protocol ensures that participants are rolled back. After system restart, the coordination service has the information about all the transactions which could have entered the commit
phase before the reboot, since they have entries in the log. It also knows about any active transactions started after the reboot. If a participant is waiting for a response, after sending its prepared
message, it automatically re sends the prepared
message at regular intervals. When the coordinator detects a transaction which is not active and has no entry in the log file after the reboot, it instructs the participant to abort, ensuring that the web service gets a chance to roll back any provisional state changes it made on behalf of the transaction.
23.1.2. WS-AT Participant Crash Recovery
prepare
, the Web service is expected to save to persistent storage the transactional state it needs to commit or roll back the transaction. The specific information it needs to save is dependent on the implementation and business logic of the Web Service. However, the participant must save this state before returning a Prepared
vote from the prepare
call. If the participant cannot save the required state, or there is some other problem servicing the request made by the client, it must return an Aborted
vote.
prepare
, commit
, and rollback
methods. The XTS implementation tracks the local state of every enlisted participant. If the prepare
call returns a Prepared
vote, the XTS implementation ensures that the participant state is logged to the local transaction log before forwarding a prepared
message to the coordinator.
commit
process to completion, or roll it back if some other Web Service fails to prepare
. This information might be as simple as a String key which the participant can use to locate the data it made persistent before returning its Prepared vote. It may be as complex as a serialized object tree containing the original participant instance and other objects created by the Web service.
commit
or rollback
method is called.
Warning
commit
method is called, a commit
or rollback
method may be called twice.
23.1.2.1. WS-AT Participant Crash Recovery APIs
23.1.2.1.1. Saving Participant Recovery State
java.lang.Serializable
interface. Alternatively it may implement Example 23.1, “The PersistableATParticipant
Interface”.
Example 23.1. The PersistableATParticipant
Interface
public interface PersistableATParticipant { byte[] getRecoveryState() throws Exception; }
Serializable
interface, the XTS participant services implementation uses the serialization API to create a version of the participant which can be appended to the participant log entry. If it implements the PersistableATParticipant
interface, the XTS participant services implementation call the getRecoveryState
method to obtain the state to be appended to the participant log entry.
23.1.2.1.2. Recovering Participants at Reboot
XTSATRecoveryManager
defined in package org.jboss.jbossts.xts.recovery.participant.at.
Example 23.2. Registering for Recovery
public abstract class XTSATRecoveryManager { . . . public static XTSATRecoveryManager getRecoveryManager() ; public void registerRecoveryModule(XTSATRecoveryModule module); public abstract void unregisterRecoveryModule(XTSATRecoveryModule module) throws NoSuchElementException; . . . }
XTSATRecoveryModule
, located in the org.jboss.jbossts.xts.recovery.participant.at, as argument to both the register
and unregister
calls. This instance is responsible for identifying saved participant recovery records and recreating new, recovered participant instances.
Example 23.3. XTSATRecoveryModule
Implementation
public interface XTSATRecoveryModule { public Durable2PCParticipant deserialize(String id, ObjectInputStream stream) throws Exception; public Durable2PCParticipant recreate(String id, byte[] recoveryState) throws Exception; }
deserialize
method is called to recreate the participant. Normally, the recovery module is required to read, cast, and return an object from the supplied input stream. If a participant's recovery state was saved using the PersistableATParticipant
interface, the recovery module's recreate
method is called to recreate the participant from the byte array it provided when the state was saved.
null
. The participant identifier, which is supplied as argument to the deserialize
or recreate
method, is the identifier used by the Web service when the original participant was enlisted in the transaction. Web Services participating in recovery processing should ensure that participant identifiers are unique per service. If a module recognizes that a participant identifier belongs to its Web service, but cannot recreate the participant, it should throw an exception. This situation might arise if the service cannot associate the participant with any transactional information which is specific to the business logic.
deserialization
operation must employ a class loader capable of loading classes specific to the Web service. XTS fulfills this requirement by devolving responsibility for the deserialize
operation to the recovery module.