org.helidb.txn
Class Transaction

java.lang.Object
  org.helidb.txn.Transaction

public class Transaction
extends Object

This object represents a database transaction. By using a database transaction, a database client can combine several database operations over several databases into one logical operation that is guaranteed to have ACID properties. Read more on ACID:ity in this Wikipedia article. At the end of the logical operation, it is either commit():ed, i.e. persisted to the database storage, or rollback():ed, i.e. discarded.

A transaction always involves just one execution thread. Several different threads may have their own transactions, and the transactions' ACID:ity properties guarantee that they will never see data in an intermediate state. This is accomplished by the thread locking implemented in the involved databases.

HeliDB has both read/write and read only transactions. It is up to the Database implementation used if they are treated differently. For instance, a Database could allow several concurrent read only transactions, but only one simultaneous transaction if that transaction is read/write.

A new transaction is started by any of the static startTransaction(boolean) or getOrStartTransaction(boolean) methods. If the thread already is involved in a transaction and wants to get that transaction's Transaction object, it can call any of the static getter methods.

Implementation note:
A database joins a Transaction via its TransactionCollaborator. It uses one collaborator object per transaction it is involved in. The collaborator keeps track of the state for the database associated with just that transaction.

Since:

1.0

Author:

Karl Gustafsson

See Also:

TransactionCollaborator, TransactionalDatabase

In_jar:

helidb-core

Constructor Summary

protected

Transaction(boolean readOnly) Create a new transaction.

Method Summary

protected void	assertNotFinished() Throw an IllegalStateException if the transaction has been finished.
void	commit() Commit the transaction.
protected void	finalize() If the transaction is still active, it is rolled back before this object is discarded.
TransactionCollaborator<?,?,?>	getCollaborator(Database<?,?> owner) Get the collaborator for the supplied object.
protected Map<Integer,TransactionCollaborator<?,?,?>>	getCollaborators() Get all collaborators and their owners for the current transaction.
static Transaction	getCurrentTransaction() Get the current transaction for the calling thread.
static Transaction	getCurrentTransactionOrNull() Get the current transaction for the calling thread.
static Transaction	getOrStartTransaction(boolean readOnly) Get the current transaction, possibly starting a new transaction if there is not one already.
boolean	isFinished() Is this transaction finished, i.e.
boolean	isReadOnly() Is this transaction read only?
void	rollback() Roll back the transaction.
TransactionCollaborator<?,?,?>	setCollaborator(Database<?,?> owner, TransactionCollaborator<?,?,?> cbr) Register a collaborator.
static Transaction	startTransaction(boolean readOnly) Start a new transaction for the calling thread.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Transaction

protected Transaction(boolean readOnly)

Create a new transaction.

Parameters:

readOnly - Should the transaction be read only?

Method Detail

isReadOnly

public boolean isReadOnly()

Is this transaction read only?

Returns:

true if this transaction is read only.

isFinished

public boolean isFinished()

Is this transaction finished, i.e. either committed or rolled back?

Returns:

true if this transaction is finished.

getCurrentTransaction

public static Transaction getCurrentTransaction()
                                         throws NoTransactionException

Get the current transaction for the calling thread.

Returns:

The current transaction.

Throws:

NoTransactionException - If there is no current transaction for the calling thread.

See Also:

getCurrentTransactionOrNull(), getOrStartTransaction(boolean), startTransaction(boolean)

getCurrentTransactionOrNull

public static Transaction getCurrentTransactionOrNull()

Get the current transaction for the calling thread.

Returns:

The current transaction, or null if there is no current transaction.

See Also:

getCurrentTransaction(), startTransaction(boolean), getOrStartTransaction(boolean)

getOrStartTransaction

public static Transaction getOrStartTransaction(boolean readOnly)
                                         throws IllegalStateException

Get the current transaction, possibly starting a new transaction if there is not one already.

Parameters:

readOnly - If a new transaction is started, should it be read only?

Returns:

The thread's current transaction. Never null.

Throws:

IllegalStateException - If the client is trying to get a read/write transaction when the thread is participating in a read only transaction.

See Also:

startTransaction(boolean), getCurrentTransaction(), getCurrentTransactionOrNull()

startTransaction

public static Transaction startTransaction(boolean readOnly)
                                    throws IllegalStateException

Start a new transaction for the calling thread.

Parameters:

readOnly - Should the transaction be read only?

Returns:

The thread's new transaction.

Throws:

IllegalStateException - If the calling thread already has a transaction.

assertNotFinished

protected void assertNotFinished()
                          throws IllegalStateException

Throw an IllegalStateException if the transaction has been finished.

Throws:

IllegalStateException - If the transaction has been finished.

getCollaborators

protected Map<Integer,TransactionCollaborator<?,?,?>> getCollaborators()

Get all collaborators and their owners for the current transaction.

Returns:

All owners and collaborators. for the current transaction. The keys in the map are the identity hash codes for the owner objects. (See System.identityHashCode(Object).) The returned map is the actual map used by this object, so changes to it will be reflected in the object's internal state.

getCollaborator

public TransactionCollaborator<?,?,?> getCollaborator(Database<?,?> owner)
                                               throws IllegalStateException

Get the collaborator for the supplied object. This is used by a database participating in a transaction to get its collaboration object. Other clients should not call this method.

Parameters:

owner - The owner of the collaborator.

Returns:

The collaborator for the owner, possibly null if the supplied object does not have a collaborator registered with this transaction.

Throws:

IllegalStateException - If this transaction has already been committed or rolled back.

See Also:

setCollaborator(Database, TransactionCollaborator)

setCollaborator

public TransactionCollaborator<?,?,?> setCollaborator(Database<?,?> owner,
                                                      TransactionCollaborator<?,?,?> cbr)
                                               throws IllegalStateException

Register a collaborator. This is used by a database joining a transaction to set its collaboration object for this transaction. Other clients should not call this method.

Parameters:

owner - The owner of the collaborator. The owner is identified by its object instance.

cbr - The collaborator.

Returns:

The owner's previous collaborator, or null if it did not have one.

Throws:

IllegalStateException - If this transaction has already been committed or rolled back.

See Also:

getCollaborator(Database)

commit

public void commit()
            throws IllegalStateException,
                   UnableToCommitException

Commit the transaction. This persists all changes made and ends it. Future calls to getCurrentTransactionOrNull() by this thread will return null until a new transaction is started.

Throws:

IllegalStateException - If this transaction has already been committed or rolled back.

UnableToCommitException - If the transaction cannot be committed for some reason. The exception message should contain the reason why.

rollback

public void rollback()
              throws IllegalStateException

Roll back the transaction. This discards all changes made and ends it. Future calls to getCurrentTransactionOrNull() by this thread will return null until a new transaction is started.

Throws:

IllegalStateException - If this transaction has already been committed or rolled back.

finalize

protected void finalize()
                 throws Throwable

If the transaction is still active, it is rolled back before this object is discarded.

Overrides:

finalize in class Object

Throws:

Throwable