com.bluegosling.concurrent.atoms

Class Transaction.Runner

java.lang.Object

com.bluegosling.concurrent.atoms.Transaction.Runner

Enclosing class:

Transaction

public static class Transaction.Runner
extends Object

An object that can initiate execution of code in a transaction. The isolation level of the transaction as well as thresholds for certain types of failures can be defined prior to running the transaction.

If otherwise unspecified, the default isolation level is Transaction.IsolationLevel.SNAPSHOT. Similarly, if unspecified, the default maximum number of isolation failures is 1000, and the default maximum number of deadlock failures is 10.

Constructor Summary

Constructors

Constructor and Description
Runner()

Method Summary

Modifier and Type	Method and Description
<T,X extends Throwable> T	compute(Transaction.Computation<T,X> computation) Performs the specified computation in a transaction and returns its result.
<T,X extends Throwable> T	computeNonIdempotent(Transaction.Computation<T,X> computation) Performs the specified computation in a transaction and returns its result.
<X extends Throwable> void	execute(Transaction.Task<X> task) Performs the specified task in a transaction.
<X extends Throwable> void	executeNonIdempotent(Transaction.Task<X> task) Performs the specified task in a transaction.
Transaction.Runner	maxDeadlockFailures(int maxFailures) Defines the maximum number of deadlock failures in a transaction.
Transaction.Runner	maxIsolationFailures(int maxFailures) Defines the maximum number of isolation failures in a transaction.
Transaction.Runner	withIsolationLevel(Transaction.IsolationLevel level) Runs transactions using the specified isolation level.

Methods inherited from class java.lang.Object

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

Constructor Detail

Runner

public Runner()

Method Detail

withIsolationLevel

public Transaction.Runner withIsolationLevel(Transaction.IsolationLevel level)

Runs transactions using the specified isolation level.

Parameters:

level - the isolation level in which to run transactions

Returns:

this, for method chaining

Throws:

NullPointerException - if the specified isolation level is null

maxIsolationFailures

public Transaction.Runner maxIsolationFailures(int maxFailures)

Defines the maximum number of isolation failures in a transaction. Such a failure occurs when a TransactionIsolationException is thrown while running the transaction. After this many failures have been observed, the transaction is aborted and the last observed exception is propagated. If the transaction is not idempotent, the specified value is ignored as such transactions are never retried.

The minimum valid value is one, which means that after observing just one such failure, the transaction is aborted.

Parameters:

maxFailures - the maximum number of isolation failures

Returns:

this, for method chaining

Throws:

IllegalArgumentException - if the specified number of failures is less than one

maxDeadlockFailures

public Transaction.Runner maxDeadlockFailures(int maxFailures)

Defines the maximum number of deadlock failures in a transaction. Such a failure occurs when a DeadlockException is thrown while running the transaction. After this many failures have been observed, the transaction is aborted and the last observed exception is propagated. If the transaction is not idempotent, the specified value is ignored as such transactions are never re-tried.

The minimum valid value is one, which means that after observing just one such failure, the transaction is aborted.

Parameters:

maxFailures - the maximum number of deadlock failures

Returns:

this, for method chaining

Throws:

IllegalArgumentException - if the specified number of failures is less than one

compute

public <T,X extends Throwable> T compute(Transaction.Computation<T,X> computation)
                                  throws X extends Throwable

Performs the specified computation in a transaction and returns its result. The computation is assumed to be idempotent, which means may be re-tried if certain failures are observed. If such failures happen too many times, exceptions are propagated.

If the computation has side effects, then it may not tolerate being re-tried and may not be idempotent. For such computations, use Transaction.computeNonIdempotent(Computation) instead.

Parameters:

computation - the computation to perform in a transaction

Returns:

the result of the computation

Throws:

IllegalStateException - if a transaction is already in progress on the current thread

X - a type of exception thrown by the computation

TransactionIsolationException - if there is too much contention over the atoms such that the computation cannot be performed with the proper isolation level

DeadlockException - if this computation generated deadlock exceptions when accessing and modifying atoms

X extends Throwable

execute

public <X extends Throwable> void execute(Transaction.Task<X> task)
                                   throws X extends Throwable

Performs the specified task in a transaction. The task is assumed to be idempotent, which means may be re-tried if certain failures are observed. If such failures happen too many times, exceptions are propagated.

If the task has side effects, then it may not tolerate being re-tried and may not be idempotent. For such tasks, use Transaction.executeNonIdempotent(Task) instead.

Parameters:

task - the task to perform in a transaction

Throws:

IllegalStateException - if a transaction is already in progress on the current thread

X - a type of exception thrown by the task

TransactionIsolationException - if there is too much contention over the atoms such that the task cannot be performed with the proper isolation level

DeadlockException - if this task generated deadlock exceptions when accessing and modifying atoms

X extends Throwable

computeNonIdempotent

public <T,X extends Throwable> T computeNonIdempotent(Transaction.Computation<T,X> computation)
                                               throws X extends Throwable

Performs the specified computation in a transaction and returns its result. The computation will not be re-tried.

If the computation has no side effects and is idempotent, then it is less likely to be aborted if you use Transaction.compute(Computation) instead.

Parameters:

computation - the computation to perform in a transaction

Returns:

the result of the computation

Throws:

IllegalStateException - if a transaction is already in progress on the current thread

X - a type of exception thrown by the computation

TransactionIsolationException - if there is contention over the atoms that prevent the computation from running with the proper isolation level

DeadlockException - if this computation generated a deadlock exception when accessing and modifying atoms

X extends Throwable

executeNonIdempotent

public <X extends Throwable> void executeNonIdempotent(Transaction.Task<X> task)
                                                throws X extends Throwable

Performs the specified task in a transaction. The task will not be re-tried.

If the task has no side effects and is idempotent, then it is less likely to be aborted if you use Transaction.execute(Task) instead.

Parameters:

task - the task to perform in a transaction

Throws:

IllegalStateException - if a transaction is already in progress on the current thread

X - a type of exception thrown by the task

TransactionIsolationException - if there is contention over the atoms that prevent the task from running with the proper isolation level

DeadlockException - if this task generated a deadlock exception when accessing and modifying atoms

X extends Throwable