org.multiverse.templates
Class TransactionTemplate<E>

java.lang.Object
  org.multiverse.templates.TransactionTemplate<E>

All Implemented Interfaces:

MultiverseConstants

public abstract class TransactionTemplate<E>
extends Object
implements MultiverseConstants

A Template that handles the boilerplate code for transactions. A transaction will be started if none is available around a section and if all goes right, the transaction is committed at the end.

example:

 new TransactionTemplate(){
    Object execute(Transaction t){
        queue.push(1);
        return null;
    }
 }.execute();
 

TransactionFactories

Some of the methods of the TransactionTemplate don't need a TransactionFactory and createReference read tracking update transaction by default. But if you want a better performance, you need to pass your own TransactionFactory. One of the biggest reasons is that the system else is not able to do runtime optimizations like selecting better transaction implementation.

Ignoring ThreadLocalTransaction

Out of the box the TransactionTemplate checks the ThreadLocalTransaction for a running transaction, and if one is available, it doesn't createReference its own. But in some cases you don't want to rely on a threadlocal, for example when you are not using instrumentation, it is possible to totally ignore the ThreadLocalTransaction.

Exceptions

All uncaught throwable's lead to a rollback of the transaction.

Threadsafe

TransactionTemplate is thread-safe to use and can be reused. So in case of an actor, you could create one instance in the beginning, and reuse the instance.

Transaction reuse

The TransactionTemplate is able to reuse transactions stored in the TransactionThreadLocal that were created by the same transaction family. For agents this is very useful, since each agent will repeatedly execute the same transaction. This is good for performance since less objects need to be created. Nothing special needs to be done to activate this behavior.

Author:

Peter Veentjer

Field Summary

Fields inherited from interface org.multiverse.MultiverseConstants

___BUGSHAKER_ENABLED, ___TRACING_ENABLED

Constructor Summary

TransactionTemplate()
Creates a new TransactionTemplate that uses the STM stored in the GlobalStmInstance and works the the ThreadLocalTransaction.

TransactionTemplate(Stm stm)
Creates a new TransactionTemplate using the provided STM.

TransactionTemplate(TransactionFactory transactionFactory)
Creates a new TransactionTemplate with the provided TransactionFactory and that is aware of the ThreadLocalTransaction.

TransactionTemplate(TransactionFactory transactionFactory, boolean threadLocalAware, boolean lifecycleListenersEnabled)
Creates a new TransactionTemplate with the provided TransactionFactory.

Method Summary

E	execute() Executes the template.
abstract E	execute(Transaction tx) This is the method that needs to be implemented.
E	executeChecked() Executes the Template and rethrows the checked exception instead of wrapping it in a InvisibleCheckedException.
TransactionFactory	getTransactionFactory() Returns the TransactionFactory this TransactionTemplate uses to createReference Transactions.
boolean	isLifecycleListenersEnabled() Checks if the lifecycle listeners on this TransactionTemplate have been enabled.
boolean	isThreadLocalAware() Checks if the TransactionTemplate should work together with the ThreadLocalTransaction.
protected void	onInit() Lifecycle method that is called when this TransactionTemplate is about to begin.
protected void	onPostAbort() Transaction lifecycle method that is called before an abort is executed.
protected void	onPostCommit() Lifecycle method that is called when this TransactionTemplate has executed a commit.
protected void	onPostStart(Transaction tx) Lifecycle method that is called every time the transaction is started.
protected void	onPreAbort(Transaction tx) Transaction Lifecycle method that is called after a transaction was aborted.
protected void	onPreCommit(Transaction tx) Lifecycle method that is called when this TransactionTemplate wants to execute.

Methods inherited from class java.lang.Object

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

Constructor Detail

TransactionTemplate

public TransactionTemplate()

Creates a new TransactionTemplate that uses the STM stored in the GlobalStmInstance and works the the ThreadLocalTransaction. It automatically creates update transactions that are able to track reads.

This constructor should only be used for experimentation purposes. If you want something fast, you need to pass in a TransactionFactory.

TransactionTemplate

public TransactionTemplate(Stm stm)

Creates a new TransactionTemplate using the provided STM. The transaction used is stores/retrieved from the ThreadLocalTransaction.

It automatically creates read tracking update transactions.

This constructor should only be used for experimentation purposes. If you want something fast, you need to pass in a TransactionFactory.

Parameters:

stm - the stm to use for transactions.

Throws:

NullPointerException - if stm is null.

TransactionTemplate

public TransactionTemplate(TransactionFactory transactionFactory)

Creates a new TransactionTemplate with the provided TransactionFactory and that is aware of the ThreadLocalTransaction.

Parameters:

transactionFactory - the TransactionFactory used to createReference Transactions.

Throws:

NullPointerException - if txFactory is null.

TransactionTemplate

public TransactionTemplate(TransactionFactory transactionFactory,
                           boolean threadLocalAware,
                           boolean lifecycleListenersEnabled)

Creates a new TransactionTemplate with the provided TransactionFactory.

Parameters:

transactionFactory - the TransactionFactory used to createReference Transactions.

threadLocalAware - true if this TransactionTemplate should look at the ThreadLocalTransaction and publish the running transaction there.

lifecycleListenersEnabled - true if the lifecycle callback methods should be enabled. Enabling them causes extra object creation, so if you want to squeeze out more performance, set this to false at the price of not having the lifecycle methods working.

Method Detail

execute

public abstract E execute(Transaction tx)
                   throws Exception

This is the method that needs to be implemented.

Parameters:

tx - the transaction used for this execution.

Returns:

the result of the execution.

Throws:

Exception - the Exception thrown

isThreadLocalAware

public final boolean isThreadLocalAware()

Checks if the TransactionTemplate should work together with the ThreadLocalTransaction.

Returns:

true if the TransactionTemplate should work together with the ThreadLocalTransaction.

isLifecycleListenersEnabled

public final boolean isLifecycleListenersEnabled()

Checks if the lifecycle listeners on this TransactionTemplate have been enabled. Disabling it reduces object creation.

Returns:

true if the lifecycle listener has been enabled, false otherwise.

getTransactionFactory

public final TransactionFactory getTransactionFactory()

Returns the TransactionFactory this TransactionTemplate uses to createReference Transactions.

Returns:

the TransactionFactory this TransactionTemplate uses to createReference Transactions.

onInit

protected void onInit()

Lifecycle method that is called when this TransactionTemplate is about to begin. It will be called once.

If this TransactionTemplate doesn't starts its own transaction, this method won't be called.

If an exception is thrown while executing this method, the execute and transaction will abort.

onPostStart

protected void onPostStart(Transaction tx)

Lifecycle method that is called every time the transaction is started. It could be that a transaction is retried (for example because of a read or write conflict or because of a blocking transaction).

If this TransactionTemplate doesn't starts its own transaction, this method won't be called.

If an exception is thrown while executing this method, the execute and transaction will abort.

Parameters:

tx - the Transaction that is started.

onPreCommit

protected void onPreCommit(Transaction tx)

Lifecycle method that is called when this TransactionTemplate wants to execute.

If this TransactionTemplate doesn't starts its own transaction, this method won't be called.

It could be that this method is called 0 to n times. 0 if the transaction didn't made it to the commit part, and for every attempt to commit.

If this method throws a Throwable, the transaction will not be committed but aborted instead.

It could be that this method is called more than once because a template could be retrying the transaction.

Parameters:

tx - the Transaction that wants to commit.

onPostCommit

protected void onPostCommit()

Lifecycle method that is called when this TransactionTemplate has executed a commit.

If an Throwable is thrown, the changes remain committed back but it could lead to not notifying all explicitly registered TransactionLifecycleListener.

If this TransactionTemplate doesn't starts its own transaction, this method won't be called.

This method will receive 1 call at the most, unless the template is reused of course.

onPreAbort

protected void onPreAbort(Transaction tx)

Transaction Lifecycle method that is called after a transaction was aborted.

If an Error/RuntimeException is thrown, it could lead to not notifying all explicitly registered TransactionLifecycleListener. But the transaction will always abort.

If this TransactionTemplate doesn't starts its own transaction, this method won't be called.

It could be that this method is called more than once because a template could be retrying the transaction.

Parameters:

tx - the transaction that currently is in the process of being aborted.

onPostAbort

protected void onPostAbort()

Transaction lifecycle method that is called before an abort is executed.

If an Error/RuntimeException is thrown, it could lead to not notifying all explicitly registered TransactionLifecycleListener.

If this TransactionTemplate doesn't starts its own transaction, this method won't be called.

It could be that this method is called more than once because a template could be retrying the transaction.

execute

public final E execute()

Executes the template. This is the method you want to call if you are using the template.

Returns:

the result of the execute(org.multiverse.api.Transaction) method.

Throws:

InvisibleCheckedException - if a checked exception was thrown while executing the execute(org.multiverse.api.Transaction) method.

DeadTransactionException - if the exception was explicitly aborted.

TooManyRetriesException - if the template retried the transaction too many times. The cause of the last failure (also an exception) is included as cause. So you have some idea where to look for problems

executeChecked

public final E executeChecked()
                       throws Exception

Executes the Template and rethrows the checked exception instead of wrapping it in a InvisibleCheckedException.

Returns:

the result

Throws:

Exception - the Exception thrown inside the execute(org.multiverse.api.Transaction) method.

DeadTransactionException - if the exception was explicitly aborted.

TooManyRetriesException - if the template retried the transaction too many times. The cause of the last failure (also an exception) is included as cause. So you have some idea where to look for problems