BasicAction (Narayana: ArjunaJTA narayana-jta 5.0.0.M6 API)

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

Fields
Modifier and Type	Field and Description
`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, objectModel, objectUid, usingActions

Constructor Summary

Constructors
Modifier	Constructor and Description
	`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.

Method Summary

Methods
Modifier and Type	Method and Description
`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(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(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`	`async_prepare(boolean reportHeuristics)`
`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.
`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, AbstractRecord record)`
`protected int`	`End(boolean reportHeuristics)` End the atomic action by committing it.
`boolean`	`equals(Object obj)`
`void`	`finalizeInternal()` 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()`
`ParticipantStore`	`getStore()` Set up an object store and assign it to the participantStore variable.
`int`	`hashCode()`
`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(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.
`protected void`	`setCheckedAction(CheckedAction c)` Add the specified CheckedAction object to this transaction.
`protected void`	`setHeuristicDecision(int p)` WARNING: use with extreme care!
`int`	`status()`
`BasicAction`	`topLevelAction()`
`Uid`	`topLevelActionUid()` The following function returns the Uid of the top-level atomic action.
`String`	`toString()` Overloads Object.toString()
`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
cleanup, createLists, 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

- 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)
```
    Recreate the specified transaction. Used for crash recovery purposes.
- Method Detail
  - finalizeInternal
```
public void finalizeInternal()
```
    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!
  - 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 ParticipantStore getStore()
```
    Set up an object store and assign it to the participantStore variable.
    
    Overrides:
    
    getStore in class StateManager
    
    Returns:
    the object store implementation to use.
    See Also:
    ObjectStore
  - 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(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(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(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.
  - 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.
  - removeChildAction
```
public final boolean removeChildAction(BasicAction act)
```
    Remove a child action.
    
    Returns:
    true if successful, false otherwise.
  - setCheckedAction
```
protected final void setCheckedAction(CheckedAction c)
```
    Add the specified CheckedAction object to this transaction.
    
    See Also:
    CheckedAction
  - getSavingUid
```
public Uid getSavingUid()
```
    Returns:
    the Uid that the transaction's intentions list will be saved under.
  - toString
```
public String toString()
```
    Overloads Object.toString()
    
    Overrides:
    
    toString in class Object
  - 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 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 Object[] childTransactions()
```
    Returns:
    the list of child transactions. Currently only their ids are given.
    Since:
    
    JTS 2.2.
  - equals
```
public boolean equals(Object obj)
```
    Overrides:
    
    equals in class Object
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class Object
  - 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)
                           throws Error
```
    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().
    
    Throws:
    
    Error - JBTM-895 tests, byteman limitation
  - 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.
  - async_prepare
```
protected int async_prepare(boolean reportHeuristics)
```
  - 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. Note that if 1PC optimisation is enabled then it is possible for prepare to dynamically optimise and commit if the first N-1 participants return read-only, causing the protcol to commit the last participant rather than go through prepare.
  - 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.)
  - setHeuristicDecision
```
protected final void setHeuristicDecision(int p)
```
    WARNING: use with extreme care!
  - 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,
            AbstractRecord record)
```
  - 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()
```

Class BasicAction

Field Summary

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

Constructor Summary

Method Summary

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

Methods inherited from class java.lang.Object

Field Detail

pendingList

preparedList

readonlyList

failedList

heuristicList

savedIntentionList

Constructor Detail

BasicAction

BasicAction

BasicAction

BasicAction

Method Detail

finalizeInternal

getHierarchy

preventCommit

activeThreads

add

hierarchyDepth

isAncestor

parent

typeOfAction

status

getStore

topLevelActionUid

topLevelAction

activate

activate

deactivate

addChildThread

addChildThread

removeChildThread

removeChildThread

addChildAction

save_state

removeChildAction

setCheckedAction

getSavingUid

toString

restore_state

type

Current

maintainHeuristics

destroy

childTransactions

equals

hashCode

forgetHeuristics

Begin

End

Abort

criticalStart

criticalEnd

phase2Cleanup

phase2Commit

phase2Abort

async_prepare

prepare

onePhaseCommit

getHeuristicDecision

setHeuristicDecision

addRecord

preparedStatus

abortStatus

commitStatus

doPrepare

doCommit

doCommit

doAbort

doAbort

insertRecord

checkForCurrent

updateHeuristic