Package com.arjuna.ats.arjuna.coordinator

Class 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 Detail

      • heuristicList

        protected RecordList heuristicList

      • savedIntentionList

        protected boolean savedIntentionList

      • subordinate

        protected boolean subordinate

      • threadStackTraceHistoryList

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

    • 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

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

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

      • 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

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

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