BNZTransaction.h



Constants

kNoTransactionForCurrentThreadException

Abstract: an exception type that is thrown when the caller of a transaction commit or rollback is in another thread than the transaction's thread

every transaction is associated with a single thread. This is, because things can only "go wrong" when threads interfere when changing data; so within one thread, the execution order is clear. This means, that a transaction can only be committed or rolled back within the same thread as it has been created in.

Note: Usually, this in nothing the programmer has to deal with, because the currentTransaction of BNZTransactionalNotificationCenter always returns the transaction for the current thread. But it may be unsafe to retrieve a transaction, store it somewhere and commit it later, when there may be a change in the executing thread or when the transaction is passed to another thread


kNotAnActiveTransactionException

an exception type that is thrown when a transaction has already been committed or rolled back and any method is called that changes the internal state of the transaction (i.e., not only retrieve data from the transaction). These methods are: prepare, commit, rollback, turnOffAutoCommit, setRollbackOnly, and addAtomicChange


Enumerations

BNZTransactionStatus

Abstract: this enumeration lists all possible states a transaction can be in
enum BNZTransactionStatus {
  ACTIVE, //A transaction is associated with the target object and it is in the active state.
  COMMITTED, //A transaction is associated with the target object and it has been committed.
  COMMITTING, //A transaction is associated with the target object and it is in the process of committing.
  MARKED_ROLLBACK, //A transaction is associated with the target object and it has been marked for rollback, perhaps as a result of a setRollbackOnly operation.
  PREPARED, //A transaction is associated with the target object and it has been prepared.
  PREPARING, //A transaction is associated with the target object and it is in the process of preparing.
  ROLLED_BACK, //A transaction is associated with the target object and the outcome has been determined to be rollback.
  ROLLING_BACK, //A transaction is associated with the target object and it is in the process of rolling back.  
} ;

Every transaction is in a defined state at any time. It starts in state ACTIVE which means that new changes can be added to the transaction and it waits for being committed or rolled back.

During the process of committing, a transaction goes into COMMITTING state, and after the successful commit it is COMMITTED.

When it is in the process of rolling back it has state ROLLING_BACK and ROLLED_BACK after a finishing the rollback.

Before rolling back or committing, the transaction has to find out about which objects have to be informed about the transaction (the observers). This is done in the preparation phase. During finding all the observers, the transaction is in PREPARING, after finishing the search it is in PREPAERD. The preparation is done automatically during commit or rollback if needed, but it can be programmatically invoced before by calling prepare.

While a transaction is ACTIVE, it can be set to MARKED_ROLLBACK by calling setRollBackOnly. The transaction can then be used as if it was active, but the only possible outcome of a later commit is a rollback.


(Last Updated 8/31/2006)