Package 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 Details

    • pendingList

      protected RecordList pendingList

    • preparedList

      protected RecordList preparedList

    • readonlyList

      protected RecordList readonlyList

    • failedList

      protected RecordList failedList

    • heuristicList

      protected RecordList heuristicList

    • savedIntentionList

      protected boolean savedIntentionList

    • subordinate

      protected boolean subordinate

    • threadStackTraceHistoryList

      protected final List<com.arjuna.ats.arjuna.coordinator.StackTraceCapture> threadStackTraceHistoryList

  • Constructor Details

    • 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 Details

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • childTransactions

      public final Object[] childTransactions()
      Returns:
      the list of child transactions. Currently only their ids are given.
      Since:
      JTS 2.2.

    • getDeferredThrowables

      public List<Throwable> getDeferredThrowables()
      Get any Throwable that was caught during commit processing but not directly rethrown.
      Returns:
      a list of ThrowableS, if any

    • 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.

    • Abort

      protected int Abort(boolean applicationAbort)
      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.
      Parameters:
      applicationAbort - indicates whether or not this is an application abort
      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. Phase 2 should only be called if phase 1 has completed successfully. 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!

    • onePhaseCommit

      protected void onePhaseCommit(boolean reportHeuristics, boolean permitReportStatistics)
      See onePhaseCommit(boolean) This method may be called during 2PC prepare when the first resource returns read-only.

    • 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()

    • recordStackTraces

      protected void recordStackTraces()

    • outputCapturedStackTraces

      protected void outputCapturedStackTraces()

    • createStackTraces

      protected Map<String,String> createStackTraces()