com.arjuna.ats.arjuna.coordinator
Class BasicAction

java.lang.Object
  com.arjuna.ats.arjuna.StateManager
      com.arjuna.ats.arjuna.coordinator.BasicAction

Direct Known Subclasses:

TwoPhaseCoordinator

public class BasicAction

extends StateManager

BasicAction does most of the work of an atomic action, but does not manage thread scoping. This is the responsibility of any derived classes.

Since:

JTS 1.0.

Version:

$Id: BasicAction.java 2342 2006-03-30 13:06:17Z $

Author:

Mark Little (mark@arjuna.com)

Field Summary

protected RecordList	failedList
protected RecordList	heuristicList
protected RecordList	pendingList
protected RecordList	preparedList
protected RecordList	readonlyList
protected boolean	savedIntentionList

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

modifyingActions, objectName, objectUid, smAttributes, usingActions

Constructor Summary

	BasicAction()
protected	BasicAction(int at) Create a transaction of the specified type.
	BasicAction(Uid objUid) BasicAction constructor with a Uid.
protected	BasicAction(Uid u, int at) Recreate the specified transaction.
protected	BasicAction(Uid u, int at, ObjectName objectName)

Method Summary

protected int	Abort() This is the user callable abort operation.
protected int	abortStatus()
boolean	activate() Overloaded version of activate -- sets up the store, performs read_state followed by restore_state.
boolean	activate(java.lang.String root) Overloaded version of activate -- sets up the store, performs read_state followed by restore_state.
int	activeThreads()
int	add(AbstractRecord A) Add a record to the atomic action.
boolean	addChildAction(BasicAction act) Add a new child action to the atomic action.
boolean	addChildThread() Add the current thread to the list of threads associated with this transaction.
boolean	addChildThread(java.lang.Thread t) Add the specified thread to the list of threads associated with this transaction.
protected void	addRecord(AbstractRecord A) Add the specified abstract record to the transaction.
protected int	Begin(BasicAction parentAct) Atomic action Begin operation.
protected boolean	checkForCurrent() Do we want to check that a transaction can only be terminated by a thread that has it as its current transaction? The base class has this check enabled (i.e., we check), but some implementations may wish to override this.
java.lang.Object[]	childTransactions()
protected int	commitStatus()
protected void	criticalEnd() Defines the end of a critical region by resetting the critical flag.
protected void	criticalStart() Defines the start of a critical region by setting the critical flag.
static BasicAction	Current()
boolean	deactivate() This operation deactivates a persistent object.
boolean	destroy() Overloads StateManager.destroy to prevent destroy being called on a BasicAction.
protected int	doAbort(boolean reportHeuristics, AbstractRecord record)
protected int	doAbort(RecordList list_toprocess, boolean reportHeuristics)
protected int	doCommit(boolean reportHeuristics, AbstractRecord record)
protected int	doCommit(RecordList rl, boolean reportHeuristics) Walk down a record list extracting records and calling the appropriate commit function.
protected int	doPrepare(boolean reportHeuristics)
protected int	doPrepare(boolean reportHeuristics, AbstractRecord theRecord)
protected int	End(boolean reportHeuristics) End the atomic action by committing it.
boolean	equals(java.lang.Object obj)
void	finalize() BasicAction destructor.
protected boolean	forgetHeuristics() Forget any heuristics we may have received, and tell the resources which generated them to forget too.
protected int	getHeuristicDecision()
ActionHierarchy	getHierarchy() Return the action hierarchy for this transaction.
Uid	getSavingUid()
ObjectStore	getStore() Set up an object store and assign it to the currentStore variable.
int	hierarchyDepth()
protected AbstractRecord	insertRecord(RecordList reclist, AbstractRecord record)
boolean	isAncestor(Uid ancestor) boolean function that checks whether the Uid passed as an argument is the Uid for an ancestor of the current atomic action.
static boolean	maintainHeuristics() If heuristic outcomes are returned, by default we will not save the state once the forget method has been called on them (which happens as soon as we have received all outcomes from registered resources).
protected void	onePhaseCommit(boolean reportHeuristics) There is only one record on the intentions list.
BasicAction	parent()
protected void	phase2Abort(boolean reportHeuristics) Second phase of the two phase commit protocol for aborting actions.
protected void	phase2Cleanup() Cleanup phase for actions.
protected void	phase2Commit(boolean reportHeuristics) Second phase of the two-phase commit protocol for committing actions.
protected int	prepare(boolean reportHeuristics) Phase one of a two phase commit protocol.
protected int	preparedStatus()
boolean	preventCommit() Force the only outcome for the transaction to be to rollback.
boolean	removeChildAction(BasicAction act) Remove a child action.
boolean	removeChildThread() Remove a child thread.
boolean	removeChildThread(java.lang.String threadId) Remove the specified thread from the transaction.
boolean	restore_state(InputObjectState os, int ot) This assumes the various lists are zero length when it is called.
boolean	save_state(OutputObjectState os, int ot) Redefined version of save_state and restore_state from StateManager.
CheckedAction	setCheckedAction(CheckedAction c) Add the specified CheckedAction object to this transaction.
int	status()
ObjectStore	store()
BasicAction	topLevelAction()
Uid	topLevelActionUid() The following function returns the Uid of the top-level atomic action.
java.lang.String	toString() Overloads Object.toString()
java.lang.String	type() Overloads StateManager.type()
int	typeOfAction()
protected void	updateHeuristic(int p, boolean commit)
protected void	updateState()

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

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

Methods inherited from class java.lang.Object

clone, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

pendingList

protected RecordList pendingList

preparedList

protected RecordList preparedList

readonlyList

protected RecordList readonlyList

failedList

protected RecordList failedList

heuristicList

protected RecordList heuristicList

savedIntentionList

protected boolean savedIntentionList

Constructor Detail

BasicAction

public BasicAction()

BasicAction

public BasicAction(Uid objUid)

BasicAction constructor with a Uid. This constructor is for recreating an BasicAction, typically during crash recovery.

BasicAction

protected BasicAction(int at)

Create a transaction of the specified type.

BasicAction

protected BasicAction(Uid u,
                      int at,
                      ObjectName objectName)

BasicAction

protected BasicAction(Uid u,
                      int at)

Recreate the specified transaction. Used for crash recovery purposes.

Method Detail

finalize

public void finalize()

BasicAction destructor. Under normal circumstances we do very little. However there exists the possibility that this action is being deleted while still running (user forgot to commit/abort) - in which case we do an abort for him and mark all our parents as unable to commit. Additionally due to scoping we may not be the current action - but in that case the current action must be one of our nested actions so by applying abort to it we should end up at ourselves!

Overrides:

finalize in class StateManager

getHierarchy

public final ActionHierarchy getHierarchy()

Return the action hierarchy for this transaction.

preventCommit

public final boolean preventCommit()

Force the only outcome for the transaction to be to rollback. Only possible if this transaction has not (or is not) terminated.

Returns:

true if successful, false otherwise.

activeThreads

public final int activeThreads()

Returns:

the number of threads associated with this transaction.

add

public final int add(AbstractRecord A)

Add a record to the atomic action. This function returns AR_ADDED if the record is added. AR_REJECTED if the record cannot be added because the action is past the prepare phase, and IGNORED otherwise.

Returns:

AddOutcome indicating outcome.

hierarchyDepth

public final int hierarchyDepth()

Returns:

the depth of the current transaction hierarchy.

isAncestor

public final boolean isAncestor(Uid ancestor)

boolean function that checks whether the Uid passed as an argument is the Uid for an ancestor of the current atomic action.

Returns:

true if the parameter represents an ancestor, false otherwise.

parent

public final BasicAction parent()

Returns:

a reference to the parent BasicAction

typeOfAction

public final int typeOfAction()

status

public final int status()

Overrides:

status in class StateManager

Returns:

the status of the BasicAction

getStore

public ObjectStore getStore()

Set up an object store and assign it to the currentStore variable.

Overrides:

getStore in class StateManager

Returns:

the object store implementation to use.

See Also:

ObjectStore

store

public final ObjectStore store()

topLevelActionUid

public final Uid topLevelActionUid()

The following function returns the Uid of the top-level atomic action. If this is the top-level transaction then it is equivalent to calling get_uid().

Returns:

the top-level transaction's Uid.

topLevelAction

public final BasicAction topLevelAction()

Returns:

a reference to the top-level transaction. If this is the top-level transaction then a reference to itself will be returned.

activate

public boolean activate()

Overloaded version of activate -- sets up the store, performs read_state followed by restore_state. The store root is null.

Overrides:

activate in class StateManager

Returns:

true if successful, false otherwise.

See Also:

ObjectStore

activate

public boolean activate(java.lang.String root)

Overloaded version of activate -- sets up the store, performs read_state followed by restore_state. The root of the object store to use is specified in the root parameter.

Overrides:

activate in class StateManager

Returns:

true if successful, false otherwise.

See Also:

ObjectStore

deactivate

public boolean deactivate()

This operation deactivates a persistent object. It behaves in a similar manner to the activate operation, but has an extra argument which defines whether the object's state should be committed or written as a shadow. The root of the object store is null. It is assumed that this is being called during a transaction commit.

Overrides:

deactivate in class StateManager

Returns:

true on success, false otherwise.

addChildThread

public final boolean addChildThread()

Add the current thread to the list of threads associated with this transaction.

Returns:

true if successful, false otherwise.

addChildThread

public final boolean addChildThread(java.lang.Thread t)

Add the specified thread to the list of threads associated with this transaction.

Returns:

true if successful, false otherwise.

removeChildThread

public final boolean removeChildThread()

Remove a child thread. The current thread is removed.

Returns:

true if successful, false otherwise.

removeChildThread

public final boolean removeChildThread(java.lang.String threadId)

Remove the specified thread from the transaction.

Returns:

true if successful, false otherwise.

addChildAction

public final boolean addChildAction(BasicAction act)

Add a new child action to the atomic action.

Returns:

true if successful, false otherwise.

removeChildAction

public final boolean removeChildAction(BasicAction act)

Remove a child action.

Returns:

true if successful, false otherwise.

setCheckedAction

public final CheckedAction setCheckedAction(CheckedAction c)

Add the specified CheckedAction object to this transaction.

Returns:

the previous CheckedAction.

See Also:

CheckedAction

getSavingUid

public Uid getSavingUid()

Returns:

the Uid that the transaction's intentions list will be saved under.

toString

public java.lang.String toString()

Overloads Object.toString()

save_state

public boolean save_state(OutputObjectState os,
                          int ot)

Redefined version of save_state and restore_state from StateManager. Normal operation (no crashes): BasicAction.save_state is called after a successful prepare. This causes and BasicAction object to be saved in the object store. This object contains primarily the "intentions list" of the BasicAction. After successfully completing phase 2 of the commit protocol, the BasicAction object is deleted from the store. Failure cases: If a server crashes after successfully preparing, then upon recovery the action must be resolved (either committed or aborted) depending upon whether the co-ordinating atomic action committed or aborted. Upon server recovery, the crash recovery mechanism detects ServerBasicAction objects in the object store and attempts to activate the BasicAction object of the co-ordinating action. If this is successful then the SAA is committed else aborted. If, when processing phase 2 of the commit protocol, the co-ordinator experiences a failure to commit from one of the records then the BasicAction object is NOT deleted. It is rewritten when a new state which contains a list of the records that failed during phase 2 commit. This list is called the "failedList". The crash recovery manager will detect local BasicAction objects in addition to SAA objects in the objectstore. An attempt will be made to commit these actions. If the action contained a call to a now dead server, this action can never be resolved and the AA object can never be removed. However, if the action is purely local then after the processing is complete the removed by crash recovery.

Overrides:

save_state in class StateManager

Returns:

true if successful, false otherwise.

restore_state

public boolean restore_state(InputObjectState os,
                             int ot)

This assumes the various lists are zero length when it is called.

Overrides:

restore_state in class StateManager

Returns:

true if successful, false otherwise.

type

public java.lang.String type()

Overloads StateManager.type()

Overrides:

type in class StateManager

Current

public static BasicAction Current()

Returns:

the thread's notion of the current transaction.

maintainHeuristics

public static boolean maintainHeuristics()

If heuristic outcomes are returned, by default we will not save the state once the forget method has been called on them (which happens as soon as we have received all outcomes from registered resources). By specifying otherwise, we will always maintain the heuristic information, which may prove useful for logging and off-line resolution.

Returns:

true if the transaction should save its heuristic information, false otherwise.

destroy

public boolean destroy()

Overloads StateManager.destroy to prevent destroy being called on a BasicAction. Could be a *very* bad idea!!

Overrides:

destroy in class StateManager

Returns:

false.

See Also:

StateManager

childTransactions

public final java.lang.Object[] childTransactions()

Returns:

the list of child transactions. Currently only their ids are given.

Since:

JTS 2.2.

equals

public boolean equals(java.lang.Object obj)

forgetHeuristics

protected boolean forgetHeuristics()

Forget any heuristics we may have received, and tell the resources which generated them to forget too.

Returns:

true if heuristic information (if any) was successfully forgotten, false otherwise.

Begin

protected int Begin(BasicAction parentAct)

Atomic action Begin operation. Does not change the calling thread's notion of the current transaction.

Returns:

ActionStatus indicating outcome.

End

protected int End(boolean reportHeuristics)

End the atomic action by committing it. This invokes the prepare() operation. If this succeeds then the pendingList should be empty and the records that were formally on it will have been distributed between the preparedList and the readonlyList, also if the action is topLevel then the intention list will have been written to the object store. Then invoke phase2Commit and clean up the object store if necessary If prepare() fails invoke phase2Abort. In this case the pendingList may still contain records but phase2Abort takes care of these. Also in this case no intention list has been written. Does not change the calling thread's notion of the current transaction. Any heuristic outcomes will only be reported if the parameter is true.

Returns:

ActionStatus indicating outcome.

Abort

protected int Abort()

This is the user callable abort operation. It is invoked prior to the start of two-phase commit and hence only processes records in the pendingList (the other lists should be empty). Does not change the calling thread's notion of the current transaction.

Returns:

ActionStatus indicating outcome.

criticalStart

protected final void criticalStart()

Defines the start of a critical region by setting the critical flag. If the signal handler is called the class variable abortAndExit is set. The value of this variable is checked in the corresponding operation to end the critical region.

criticalEnd

protected final void criticalEnd()

Defines the end of a critical region by resetting the critical flag. If the signal handler is called the class variable abortAndExit is set. The value of this variable is checked when ending the critical region.

phase2Cleanup

protected final void phase2Cleanup()

Cleanup phase for actions. If an action is in the PREPARED state when a terminate signal is delivered (ie the coordinator node has crashed) then we need to cleanup. This is essentially the same as phase2Abort but we call cleanup ops rather than abort ops and let the records take care of appropriate cleanup. The pendingList is processed because it may not be empty - since prepare() stops processing the list at the first PREPARE_NOTOK result. The read_only list is processed to ensure that actions are aborted immediately and any servers killed at that point since they need not hang around. This contrasts with commit where readonlyList entries are simply merged with the parent list or discarded

phase2Commit

protected final void phase2Commit(boolean reportHeuristics)

Second phase of the two-phase commit protocol for committing actions. This operation first invokes the doCommit operation on the preparedList. This ensures that the appropriate commit operation is performed on each entry which is then either deleted (top_level) or merged into the parent's pendingList. Processing of the readonlyList is different in that if the action is top_level then all records in the readonlyList are deleted without further processing. If nested the records must be merged. This is an optimisation to avoid unnecessary processing. Note that at this point the pendingList SHOULD be empty due to the prior invocation of prepare().

phase2Abort

protected final void phase2Abort(boolean reportHeuristics)

Second phase of the two phase commit protocol for aborting actions. Actions are aborted by invoking the doAbort operation on the preparedList, the readonlyList, and the pendingList. The pendingList is processed because it may not be empty - since prepare() stops processing the list at the first PREPARE_NOTOK result. By default, records that responsed PREPARE_READONLY will not be contacted during second-phase abort, just as they are not during second-phase commit. This can be overridden at runtime using the READONLY_OPTIMISATION variable.

prepare

protected final int prepare(boolean reportHeuristics)

Phase one of a two phase commit protocol. This function returns the ouctome of the prepare operation. If all goes well it will be PREPARE_OK, if not PREPARE_NOTOK. The value PREPARE_READONLY may also be returned if all the records indicate that they are readonly records. Such records do not take part in the second phase commit processing.

Returns:

TwoPhaseOutcome indicating outcome.

onePhaseCommit

protected void onePhaseCommit(boolean reportHeuristics)

There is only one record on the intentions list. Only called from synchronized methods. Don't bother about creating separate threads here!

getHeuristicDecision

protected final int getHeuristicDecision()

Returns:

the current heuristic decision. Each time a heuristic outcome is received, we need to merge it with any previous outcome to determine what the overall heuristic decision is (e.g., a heuristic rollback followed by a heuristic commit means the overall decision is heuristic mixed.)

addRecord

protected final void addRecord(AbstractRecord A)

Add the specified abstract record to the transaction. Does not do any of the runtime checking of BasicAction.add, so should be used with care. Currently used by crash recovery.

preparedStatus

protected int preparedStatus()

Returns:

the transaction's prepared status.

Since:

JTS 2.0.

abortStatus

protected int abortStatus()

commitStatus

protected int commitStatus()

doPrepare

protected int doPrepare(boolean reportHeuristics)
                 throws java.lang.IndexOutOfBoundsException

Throws:

java.lang.IndexOutOfBoundsException

doPrepare

protected int doPrepare(boolean reportHeuristics,
                        AbstractRecord theRecord)
                 throws java.lang.IndexOutOfBoundsException

Throws:

java.lang.IndexOutOfBoundsException

doCommit

protected int doCommit(RecordList rl,
                       boolean reportHeuristics)

Walk down a record list extracting records and calling the appropriate commit function. Discard or merge records as appropriate

doCommit

protected int doCommit(boolean reportHeuristics,
                       AbstractRecord record)

doAbort

protected int doAbort(RecordList list_toprocess,
                      boolean reportHeuristics)

doAbort

protected int doAbort(boolean reportHeuristics,
                      AbstractRecord record)

insertRecord

protected AbstractRecord insertRecord(RecordList reclist,
                                      AbstractRecord record)

checkForCurrent

protected boolean checkForCurrent()

Do we want to check that a transaction can only be terminated by a thread that has it as its current transaction? The base class has this check enabled (i.e., we check), but some implementations may wish to override this.

Returns:

false to disable checking.

updateHeuristic

protected final void updateHeuristic(int p,
                                     boolean commit)

updateState

protected void updateState()