com.kabira.platform

Class Transaction

java.lang.Object

com.kabira.platform.Transaction

public abstract class Transaction
extends java.lang.Object

Executes code in the context of a transaction.

The class should be extended and the abstract run() method implemented. When executed via execute(com.kabira.platform.Transaction.Properties), all code executed within the run method will be transactional, changes to Managed objects are logged.

Object instances that are modified are write locked into the transaction, blocking access from other transactions until the transaction commits or rolls back.

If the default Transaction.IsolationLevel.SERIALIZABLE Isolation level is used, object instances that are accessed but not modified will be read locked into the transaction. This will allow other transactions to also access and read lock the object, but prevents other transactions from modifying the object.

If the Transaction.IsolationLevel.READ_COMMITTED_SNAPSHOT Isolation level is used, object instances that are accessed but not modified will have a snapshot of the data taken when first accessed in the transaction. All subseqeunt accesses to the object data within the same transaction will use this snapshot in order to present a consistent view of the data. This will allow other transactions to both access and modify the object. If a transaction takes a snapshot, and subsequently attempts to modify the object, the runtime will determine if the object data has been modified by another transaction since the snapshot was taken. If it has been modified, a deadlock exception is thrown in order to retry the transaction.

Any deadlocks that occur will automatically cause a roll back of the current transaction, and the code within the run method will be re-executed. This means that any code called within the run method must be transaction safe. If the work done within the run method should not be executed more than once, the work should be deferred until commit time by using a transaction commit trigger.

Exception handling

If the code within the run method throws a Transaction.Rollback exception with no cause, the execute call will roll back the transaction, and return Transaction.Result.ROLLBACK to the caller. In order to support exception propagation through the execute method, the following mechanisms can be used:

• If an unchecked exception is thrown in the run method, the exception will be rethrown to the caller of execute.
• If the implementor of the run method wishes to propagate a checked exception, they can throw a Rollback exception with a cause. When caught by execute, the Rollback exception cause and message will be wrapped in a Transaction.InvocationRunException and thrown back to the caller.

In both cases, the transaction is rolled back before the exception is propagated.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Transaction.Identifier Transaction identifier.
static class	Transaction.InvalidTransactionState Invalid transaction state exception.
static class	Transaction.InvocationRunException Invocation run exception.
static class	Transaction.IsolationLevel Transaction isolation levels.
static class	Transaction.NotTransactional Not transactional exception.
static class	Transaction.ObjectNotifier Locked object notifier
static class	Transaction.Properties The Transaction properties used when executing a transaction
static class	Transaction.Result Execute method return values.
static class	Transaction.Rollback Rollback exception.

Constructor Summary

Constructors

Constructor and Description
Transaction() Creates a new transaction.
Transaction(java.lang.String transactionName) Creates a new transaction.

Method Summary

Modifier and Type	Method and Description
static boolean	createdInTransaction(java.lang.Object obj) Determine if object was created in the current transaction.
static boolean	deletedInTransaction(java.lang.Object obj) Determine if object was deleted in the current transaction.
Transaction.Result	execute() Executes the user defined method within a transaction.
Transaction.Result	execute(Transaction.Properties properties) Executes the user defined method within a transaction.
static Transaction.Properties	getActiveTransactionProperties() Returns the transaction properties for the current transaction.
static Transaction.Identifier	getIdentifier() Returns the transaction identifier for the current transaction.
int	getNumberDeadlocks() Returns the number of deadlocks detected and replayed for the last call to execute().
static java.lang.String	getTransactionDescription() Returns the current setting of the transaction description.
static boolean	hasReadLock(java.lang.Object obj) Determines if a read lock exists for an object in the current transaction.
static boolean	hasWriteLock(java.lang.Object obj) Determines if a write lock exists for an object in the current transaction.
static boolean	isActive() Determines if a transaction is active.
static boolean	modifiedInTransaction(java.lang.Object obj) Determine if object was modified in the current transaction.
static void	readLockObject(java.lang.Object obj) Establishes a read lock for the given object.
protected abstract void	run() User defined method that is run in the context of a transaction.
static void	runObjectNotifier(Transaction.ObjectNotifier objectNotifier) Run an object notifier
static void	setTransactionDescription(java.lang.String description) Sets the current transaction description.
static void	writeLockObject(java.lang.Object obj) Establishes a write lock for the given object.

Methods inherited from class java.lang.Object

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

Constructor Detail

Transaction

public Transaction(java.lang.String transactionName)

Creates a new transaction.

Parameters:

transactionName - - Name associated with the transaction.

Transaction

public Transaction()

Creates a new transaction.

Method Detail

run

protected abstract void run()
                     throws Transaction.Rollback

User defined method that is run in the context of a transaction.

Throws:

Transaction.Rollback - Thrown if the transaction should be rolled back and all changes discarded.

execute

public final Transaction.Result execute(Transaction.Properties properties)
                                 throws Transaction.InvalidTransactionState,
                                        Transaction.InvocationRunException

Executes the user defined method within a transaction. Any deadlocks are transparently retried.

Parameters:

properties - - Properties used when executing the transaction.

Returns:

Result of transaction

Throws:

Transaction.InvalidTransactionState - If a transaction is already active, or the transaction services are not available.

Transaction.InvocationRunException - The execution of the run method resulted in an exception that was propagated.

execute

public final Transaction.Result execute()
                                 throws Transaction.InvalidTransactionState,
                                        Transaction.InvocationRunException

Executes the user defined method within a transaction. Any deadlocks are transparently retried.

The default isolationLevel of SERIALIZABLE is used for the transaction.

Returns:

Result of transaction

Throws:

Transaction.InvalidTransactionState - If a transaction is already active, or the transaction services are not available.

Transaction.InvocationRunException - The execution of the run method resulted in an exception that was propagated.

getIdentifier

public static final Transaction.Identifier getIdentifier()
                                                  throws java.lang.IllegalAccessError

Returns the transaction identifier for the current transaction. This only returns a valid transaction identifier when there is an active transaction.

Returns:

The current transaction identifier.

Throws:

java.lang.IllegalAccessError - No active transaction

getActiveTransactionProperties

public static final Transaction.Properties getActiveTransactionProperties()
                                                                   throws java.lang.IllegalAccessError

Returns the transaction properties for the current transaction. This only returns the properties when there is an active transaction.

Returns:

The properties for the given active transaction.

Throws:

java.lang.IllegalAccessError - No active transaction

createdInTransaction

public static boolean createdInTransaction(java.lang.Object obj)
                                    throws java.lang.IllegalAccessError

Determine if object was created in the current transaction.

This operation can be used to determine if the specified object was created in the current transaction.

Parameters:

obj - Object to check

Returns:

true if the object was created.

Throws:

java.lang.IllegalAccessError - No active transaction

ManagedClassError - If obj is not Managed.

deletedInTransaction

public static boolean deletedInTransaction(java.lang.Object obj)

Determine if object was deleted in the current transaction.

This operation can be used to determine if the specified object was deleted in the current transaction.

Warning: If an instance has been deleted in a transaction, any attempt to cast the instance to a subtype will return an empty handle.

Parameters:

obj - Object to check

Returns:

true if the object was deleted.

Throws:

java.lang.IllegalAccessError - No active transaction

ManagedClassError - If obj is not Managed.

modifiedInTransaction

public static boolean modifiedInTransaction(java.lang.Object obj)

Determine if object was modified in the current transaction.

This operation can be used to determine if the specified object was modified in the current transaction.

Parameters:

obj - Object to check

Returns:

true if the object was modified.

Throws:

java.lang.IllegalAccessError - No active transaction

ManagedClassError - If obj is not Managed.

runObjectNotifier

public static void runObjectNotifier(Transaction.ObjectNotifier objectNotifier)

Run an object notifier

When called, the inTransaction method in the ObjectNotifier is called for each locked object in the current transaction.

Parameters:

objectNotifier - Application notifier.

Throws:

java.lang.IllegalAccessError - No active transaction

isActive

public static boolean isActive()

Determines if a transaction is active.

Returns:

true if a transaction is active, false otherwise.

getTransactionDescription

public static final java.lang.String getTransactionDescription()

Returns the current setting of the transaction description.

Returns:

Description, as set via setTransactionDescription().

setTransactionDescription

public static final void setTransactionDescription(java.lang.String description)

Sets the current transaction description. The description is cleared when the transaction begins.

Parameters:

description - The value to set.

getNumberDeadlocks

public final int getNumberDeadlocks()

Returns the number of deadlocks detected and replayed for the last call to execute().

Returns:

The number of detected deadlocks.

writeLockObject

public static final void writeLockObject(java.lang.Object obj)
                                  throws java.lang.IllegalAccessError,
                                         Transaction.NotTransactional

Establishes a write lock for the given object.

Parameters:

obj - Object to lock.

Throws:

java.lang.IllegalAccessError - No active transaction

Transaction.NotTransactional - If the object passed in is not Managed.

readLockObject

public static final void readLockObject(java.lang.Object obj)
                                 throws java.lang.IllegalAccessError,
                                        Transaction.NotTransactional

Establishes a read lock for the given object.

If the current transaction isolation level is Transaction.IsolationLevel.READ_COMMITTED_SNAPSHOT, a snapshot of the data is taken and the read lock immediately released.

Parameters:

obj - Object to lock.

Throws:

java.lang.IllegalAccessError - No active transaction

Transaction.NotTransactional - If the object passed in is not Managed.

hasWriteLock

public static final boolean hasWriteLock(java.lang.Object obj)
                                  throws java.lang.IllegalAccessError,
                                         Transaction.NotTransactional

Determines if a write lock exists for an object in the current transaction.

Parameters:

obj - Object to examine.

Returns:

true if a write lock exists on object in current transaction, false otherwise.

Throws:

java.lang.IllegalAccessError - No active transaction

Transaction.NotTransactional - If the object passed in is not Managed.

hasReadLock

public static final boolean hasReadLock(java.lang.Object obj)
                                 throws java.lang.IllegalAccessError,
                                        Transaction.NotTransactional

Determines if a read lock exists for an object in the current transaction.

If the current transaction isolation level is Transaction.IsolationLevel.READ_COMMITTED_SNAPSHOT, readlocks are immediately released after a snapshot is taken. In this case hasReadLock() will always return false.

Parameters:

obj - Object to examine

Returns:

true if a read lock exists on object in current transaction, false otherwise.

Throws:

java.lang.IllegalAccessError - No active transaction

Transaction.NotTransactional - If the object passed in is not Managed.