Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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.html,v 1.1 2008/01/04 06:52:39 afitzsim Exp $
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()

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD