com.arjuna.mwlabs.wscf.model.sagas.arjunacore.subordinate

Class SubordinateBACoordinator

java.lang.Object

com.arjuna.ats.arjuna.StateManager

com.arjuna.ats.arjuna.coordinator.BasicAction

com.arjuna.ats.arjuna.coordinator.TwoPhaseCoordinator

com.arjuna.mwlabs.wscf.model.sagas.arjunacore.BACoordinator

com.arjuna.mwlabs.wscf.model.sagas.arjunacore.subordinate.SubordinateBACoordinator

All Implemented Interfaces:

com.arjuna.ats.arjuna.coordinator.Reapable

Direct Known Subclasses:

RecoverySubordinateBACoordinator

public class SubordinateBACoordinator
extends BACoordinator

This class represents a specific coordination instance. It inherits from ArjunaCore TwoPhaseCoordinator via the BACoordinator. This is the subordinate coordinator implementation which we use when doing interposition. This implementation registers itself as a coordinator completion participant in its parent activity. It has to use the coordinator completion protocol because it relies upon dispatch of a complete request from the parent to drive logging of i) the subordinate transaction state then ii) the state of its registered proxy participant. These operations must both happen in that order and only when the parent transaction is preparing to close. Note that this does not imply that the transaction is closed, merely that it goes through phase 1 of the transaction termination protocol (PREPARE) leaving a transaction log record on the disk (albeit in state COMMITTING). It must still be possible to leave phase 2 open for either close (COMMIT) or compensate (ROLLBACK). Why? Well, if the participant logs its state first either at parent complete or, if participant completion is in use, before parent complete, then a crash risks losing details of the subordinate transaction -- including potentialy completed participants which may require closing or compensating. Note that this danger bypasses any question of whether or when subsequently the subordinate transaction state might be logged -- the participant cannot log its state and guarantee to close or compensate correctly without having first ensured that it can guarantee to close or compensate subordinate participants. Contrariwise, if the subordinate transaction logs its state first and a crash occurs before the proxy participant state can be saved then it is still possible during recovery to correlate the presence of the logged subordinate transaction with the absence of its proxy participant and automatically compensate the subordinate transaction's completed participants. This will match the action of the parent since absence of the proxy participant requires it also to compensate. It is not possible to commit any earlier than parent complete because it is still legitimate for participants to register before that event. So, the implication of this is that when the proxy notifies complete to this coordinator it must perform the usual complete processing and also drive phase 1 of the commit process. Later, when a close request is dispatched, it can drive phase 2 of the commit process. If there is a failure during phase 1 of the commit process then the subordinate transaction will not be logged. In this case the proxy participant must notify a fail to the parent transaction and avoid logging its own state. This is safe because a crash will automatically cause a subsequent resend of the complete request to return fail because the proxy participant is unknown. If phase 1 completes successfully then the proxy participant must log its state and notify completed to the parent trasaction. If a crash occurs between logging the subordinate transaction state and logging the proxy state then the absence of the proxy participant can be reconciled during recovery and the subordinate transaction can be automatically compensated. If a crash occurs between logging the proxy participant and notifying completed to the parent transaction then the participant will be recreated during recovery and a subsequent resend of complete can be answered with completed. Note that this means complete requests for unknown participants must only be answered after the first pass of the BA participant recovery module has completed.

Since:

2.0.

Version:

$Id: SubordinateCoordinator.java,v 1.1 2005/05/19 12:13:39 nmcl Exp $

Author:

Mark Little (mark.little@arjuna.com)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SubordinateBACoordinator.SubordinateCallback class implemented by any code which wishes to register a callabck

Field Summary

Fields

Modifier and Type	Field and Description
static String	PARTICIPANT_PREFIX unique string used as prefix for participant ids to ensure they can be identified at recovery

Fields inherited from class com.arjuna.ats.arjuna.coordinator.BasicAction

failedList, heuristicList, pendingList, preparedList, readonlyList, savedIntentionList

Fields inherited from class com.arjuna.ats.arjuna.StateManager

modifyingActions, objectModel, objectUid, usingActions

Constructor Summary

Constructors

Constructor and Description
SubordinateBACoordinator() normal constructor
SubordinateBACoordinator(com.arjuna.ats.arjuna.common.Uid recovery) constructor for recovered coordinator

Method Summary

Methods

Modifier and Type	Method and Description
static void	addActiveProxy(String id)
static void	addCallback(String key, SubordinateBACoordinator.SubordinateCallback callback) register a callback to be called when a subordinate transaction with a specific key executes a commit or rollback.
protected static void	addRecoveredCoordinator(SubordinateBACoordinator coordinator)
int	cancel() this is driven by a coordinator-completion participant registered on behalf of the coordinator and is required to propagate the cancel to all registered participants.
int	close() this is driven by a coordinator-completion participant registered on behalf of the coordinator and is required to propagate the close to all registered participants.
void	complete() this is driven by a coordinator-completion participant registered on behalf of the coordinator and is required to propagate the complete to all registered coordinator-completion participants.
Outcome	coordinate(CompletionStatus cs) If the application requires and if the coordination protocol supports it, then this method can be used to execute a coordination protocol on the currently enlisted participants at any time prior to the termination of the coordination scope.
int	end(boolean reportHeuristics)
void	error() called by the durable participant during recovery processing TODO clarify when and why this gets called and what to do about it
String	getCoordinatorCompletionParticipantid() return a uid for the corodinator completion participant registered on behalf of this coordinator
static SubordinateBACoordinator	getRecoveredCoordinator(String coordinatorId)
boolean	isActivated()
boolean	isOrphaned() test whether a transaction has been restored without its proxy participant.
static SubordinateBACoordinator[]	listRecoveredCoordinators()
static void	removeActiveProxy(String id)
protected static void	removeRecoveredCoordinator(SubordinateBACoordinator coordinator)
protected void	setActivated()
String	type()
void	unknown() called by the durable participant during recovery processing TODO clarify when and why this gets called and what to do about it

Methods inherited from class com.arjuna.mwlabs.wscf.model.sagas.arjunacore.BACoordinator

delistParticipant, delistSynchronization, enlistParticipant, enlistSynchronization, identifier, participantCannotComplete, participantCompleted, participantFaulted, qualifiers

Methods inherited from class com.arjuna.ats.arjuna.coordinator.TwoPhaseCoordinator

addSynchronization, afterCompletion, afterCompletion, beforeCompletion, getDeferredThrowable, getSynchronizations, running, start, start

Methods inherited from class com.arjuna.ats.arjuna.coordinator.BasicAction

Abort, abortStatus, activate, activate, activeThreads, add, addChildAction, addChildThread, addChildThread, addRecord, async_prepare, Begin, checkForCurrent, childTransactions, commitStatus, criticalEnd, criticalStart, Current, deactivate, destroy, doAbort, doAbort, doCommit, doCommit, doPrepare, End, equals, finalizeInternal, forgetHeuristics, getDeferredThrowables, getHeuristicDecision, getHierarchy, getSavingUid, getStore, hashCode, hierarchyDepth, insertRecord, isAncestor, maintainHeuristics, onePhaseCommit, parent, phase2Abort, phase2Cleanup, phase2Commit, prepare, preparedStatus, preventCommit, removeChildAction, removeChildThread, removeChildThread, restore_state, save_state, setCheckedAction, setHeuristicDecision, status, topLevelAction, topLevelActionUid, toString, typeOfAction, updateHeuristic, updateState

Methods inherited from class com.arjuna.ats.arjuna.StateManager

cleanup, deactivate, deactivate, disable, forgetAction, get_uid, getMutex, getObjectModel, getStoreRoot, loadObjectState, lockMutex, modified, objectType, packHeader, persist, print, rememberAction, setStatus, setupStore, setupStore, setupStore, terminate, tryLockMutex, unlockMutex, unpackHeader

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface com.arjuna.ats.arjuna.coordinator.Reapable

get_uid, preventCommit

Field Detail

PARTICIPANT_PREFIX

public static String PARTICIPANT_PREFIX

unique string used as prefix for participant ids to ensure they can be identified at recovery

Constructor Detail

SubordinateBACoordinator

public SubordinateBACoordinator()

normal constructor

SubordinateBACoordinator

public SubordinateBACoordinator(com.arjuna.ats.arjuna.common.Uid recovery)

constructor for recovered coordinator

Parameters:

recovery -

Method Detail

coordinate

public Outcome coordinate(CompletionStatus cs)
                   throws WrongStateException,
                          ProtocolViolationException,
                          SystemException

If the application requires and if the coordination protocol supports it, then this method can be used to execute a coordination protocol on the currently enlisted participants at any time prior to the termination of the coordination scope. This implementation only supports coordination at the end of the activity.

Overrides:

coordinate in class BACoordinator

Parameters:

cs - The completion status to use when determining how to execute the protocol.

Returns:

The result of executing the protocol, or null.

Throws:

WrongStateException - Thrown if the coordinator is in a state the does not allow coordination to occur.

ProtocolViolationException - Thrown if the protocol is violated in some manner during execution.

SystemException - Thrown if any other error occurs.

end

public int end(boolean reportHeuristics)

Overrides:

end in class com.arjuna.ats.arjuna.coordinator.TwoPhaseCoordinator

complete

public void complete()
              throws WrongStateException,
                     SystemException

this is driven by a coordinator-completion participant registered on behalf of the coordinator and is required to propagate the complete to all registered coordinator-completion participants.

Overrides:

complete in class BACoordinator

Throws:

WrongStateException - if the transaction is neither RUNNING nor PREPARED

SystemException - if there are incomplete ParticipantCompletion participants or if one of the CoordinatorCompletion participants fails to complete.

close

public int close()
          throws SystemException

this is driven by a coordinator-completion participant registered on behalf of the coordinator and is required to propagate the close to all registered participants.

Overrides:

close in class BACoordinator

Returns:

Throws:

SystemException

cancel

public int cancel()

this is driven by a coordinator-completion participant registered on behalf of the coordinator and is required to propagate the cancel to all registered participants.

Specified by:

cancel in interface com.arjuna.ats.arjuna.coordinator.Reapable

Overrides:

cancel in class BACoordinator

unknown

public void unknown()

called by the durable participant during recovery processing TODO clarify when and why this gets called and what to do about it

error

public void error()

called by the durable participant during recovery processing TODO clarify when and why this gets called and what to do about it

type

public String type()

Overrides:

type in class BACoordinator

getCoordinatorCompletionParticipantid

public String getCoordinatorCompletionParticipantid()

return a uid for the corodinator completion participant registered on behalf of this coordinator

addRecoveredCoordinator

protected static void addRecoveredCoordinator(SubordinateBACoordinator coordinator)

removeRecoveredCoordinator

protected static void removeRecoveredCoordinator(SubordinateBACoordinator coordinator)

addActiveProxy

public static void addActiveProxy(String id)

removeActiveProxy

public static void removeActiveProxy(String id)

setActivated

protected void setActivated()

isActivated

public boolean isActivated()

isOrphaned

public boolean isOrphaned()

test whether a transaction has been restored without its proxy participant. this indicates that we crashed between preparing the suborindate TX and logging the proxy participant.

Returns:

getRecoveredCoordinator

public static SubordinateBACoordinator getRecoveredCoordinator(String coordinatorId)

listRecoveredCoordinators

public static SubordinateBACoordinator[] listRecoveredCoordinators()

addCallback

public static void addCallback(String key,
               SubordinateBACoordinator.SubordinateCallback callback)

register a callback to be called when a subordinate transaction with a specific key executes a commit or rollback. the callback will not be called in the case of a crash

Parameters:

key -

callback -