com.arjuna.wst11.ConfirmCompletedParticipant Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of jbossxts Show documentation
Narayana: XTS jbossxts
The newest version!
/*
   Copyright The Narayana Authors
   SPDX-License-Identifier: Apache-2.0
 */

package com.arjuna.wst11;

/**
 * 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.
 */

public interface ConfirmCompletedParticipant
{
    /**
     * a participant callback use to notify the participant either that a recovery record has been written to
     * the log and hence that uncommitted changes should be committed or that completion was cancelled and
     * hence that uncommitted changes should be rolled back.
     * @param confirmed true if the log record has been written and changes should be rolled forward and false
     * if it has not been written and changes should be rolled back
     */
    public void confirmCompleted(boolean confirmed);
}