Package org.jboss.stm.async

Class Transaction

java.lang.Object
org.jboss.stm.async.Transaction
public class Transaction extends Object
This is a user-level transaction class. Unlike AtomicAction which it uses, this provides an asynchronous begin, commit and rollback capability. There are a number of ways in which we currently support asynchronous interactions with the transaction system, such as async prepare or async commit. The developer could also register a two-phase aware participant or a Synchronisation and use callbacks themselves to determine the outcome of the transaction. These continue to be available to the developer but this API is intended to provide a simplified interface to allow clients to make use of asynchronous transactions. Note, we deliberately don't derive from AtomicAction so that developers must make a conscious choice between a synchronous or asynchronous transaction.
Version:
$Id$
Author:
Mark Little (mark@arjuna.com)

  • Constructor Details

    • Transaction

      public Transaction()
      Create a new transaction. If there is already a transaction associated with the thread then this new transaction will be automatically nested. The transaction is *not* running at this point. No timeout is associated with this transaction, i.e., it will not be automatically rolled back by the system.

    • Transaction

      public Transaction(Uid objUid)
      AtomicAction constructor with a Uid. This constructor is for recreating an AtomicAction, typically during crash recovery.

  • Method Details

    • begin

      public Future<Integer> begin()
      Start the transaction running. If the transaction is already running or has terminated, then an error code will be returned. No timeout is associated with the transaction.
      Returns:
      ActionStatus indicating outcome.

    • begin

      public Future<Integer> begin(int timeout)
      Start the transaction running. If the transaction is already running or has terminated, then an error code will be returned.
      Parameters:
      timeout - the timeout associated with the transaction. If the transaction is still active when this timeout elapses, the system will automatically roll it back.
      Returns:
      ActionStatus indicating outcome.

    • commit

      public Future<Integer> commit()
      Commit the transaction, and have heuristic reporting. Heuristic reporting via the return code is enabled.
      Returns:
      ActionStatus indicating outcome.

    • commit

      public Future<Integer> commit(boolean report_heuristics)
      Commit the transaction. The report_heuristics parameter can be used to determine whether or not heuristic outcomes are reported. If the transaction has already terminated, or has not begun, then an appropriate error code will be returned.
      Returns:
      ActionStatus indicating outcome.

    • abort

      public Future<Integer> abort()
      Abort (rollback) the transaction. If the transaction has already terminated, or has not been begun, then an appropriate error code will be returned.
      Returns:
      ActionStatus indicating outcome.

    • getTimeout

      public final int getTimeout()

    • type

      public String type()
      The type of the class is used to locate the state of the transaction log in the object store. Overloads BasicAction.type()
      Returns:
      a string representation of the hierarchy of the class for storing logs in the transaction object store.

    • suspend

      public static final Transaction suspend()
      Suspend all transaction association from the invoking thread. When this operation returns, the thread will be associated with no transactions. If the current transaction is not an AtomicAction then this method will not suspend. Note, we do not provide an async version of suspend because it would be wrong for an application thread to proceed under the assumption it had succeeded/happened yet. Ordering of events makes a difference here.
      Returns:
      a handle on the current AtomicAction (if any) so that the thread can later resume association if required.

    • resume

      public static final boolean resume(Transaction act)
      Resume transaction association on the current thread. If the specified transaction is null, then this is the same as doing a suspend. If the current thread is associated with transactions then those associations will be lost. Note, we do not provide an async version of resume because it would be wrong for an application thread to proceed under the assumption it had succeeded/happened yet. Ordering of events makes a difference here.
      Parameters:
      act - the transaction to associate. If this is a nested transaction, then the thread will be associated with all of the transactions in the hierarchy.
      Returns:
      true if association is successful, false otherwise.