Package de.xima.fc.persistence.tx

Interface JpaTransactionRunner

public interface JpaTransactionRunner

Runs a unit of work in a JPA transaction of the system database, taking part in the transaction the calling thread already runs in if there is one. The caller neither opens nor closes anything:

 final CapabilityDTO dto = runner.inTransaction(uow -> {
     ... work with uow.em() ...
     return dto;
 });
 

The transaction is committed when the work returns normally, and rolled back if it throws anything, which is then rethrown unchanged. If the transaction belongs to a caller further out, the work is instead flushed into it and that caller decides whether it is committed, while work that failed leaves the transaction uncommittable, so a caller that ignores the failure cannot commit an incomplete unit of work either.

Return DTOs, never entities or lazy proxies. Entities are detached once the transaction is over and an unresolved lazy association then fails on access.

Code that needs to control the transaction boundary itself keeps using SystemPersistenceManager.openTransaction(), which always opens a transaction of its own that nothing else takes part in.

Since:

8.5.6

Author:

Norman Lorenz

Method Summary

Modifier and Type	Method	Description
void	afterCommit(Runnable action)	Runs the given action once the transaction the calling thread runs in has been committed, for work that must not take effect before the unit of work is durable, such as publishing an event.
static JpaTransactionRunner	getInstance()	Retrieves the singleton instance of the JpaTransactionRunner via CDI.
<T,E extends Exception> T	inTransaction(JpaWork<T,E> work)	Runs the given work in a transaction and returns its result.
boolean	isTransactionActive()	Whether the calling thread runs in a transaction, that is whether it is inside a unit of work.
void	markRollbackOnly()	Prevents the transaction the calling thread runs in from being committed, for work that found a reason not to commit but does not report it as an exception.
<E extends Exception> void	runInTransaction(JpaTask<E> work)	Runs the given work in a transaction.

Method Detail

afterCommit

void afterCommit(Runnable action)

Runs the given action once the transaction the calling thread runs in has been committed, for work that must not take effect before the unit of work is durable, such as publishing an event. A rolled back transaction discards its actions without running them.

The action runs on the calling thread, after the entity manager of the transaction is closed and after the transaction stopped being the current one. It therefore cannot use that entity manager, and work of its own that needs the database has to run as a new unit of work. Anything it throws is logged and swallowed, because the transaction is already committed and there is nothing left to undo.

Actions run in the order they were registered. An action registered by a unit of work that took part in the transaction of a caller further out belongs to that caller's transaction, so it runs when the outermost unit of work is committed.

Parameters:

action - the action to run after the commit. Must not be null.

Throws:

IllegalArgumentException - if the action is null.

IllegalStateException - if the calling thread does not run in a transaction.

Since:

8.5.6

getInstance

static JpaTransactionRunner getInstance()

Retrieves the singleton instance of the JpaTransactionRunner via CDI.

Returns:

the singleton instance of JpaTransactionRunner.

Throws:

IllegalStateException - if the CDI container is not available or the bean cannot be found.

Since:

8.5.6

inTransaction

<T,E extends Exception> T inTransaction(JpaWork<T,E> work)
                                       throws E extends Exception,
                                              FcPersistenceException

Runs the given work in a transaction and returns its result.

Type Parameters:

T - the type of the result. Must be a DTO, not an entity.

E - the type of the checked exception the work may throw.

Parameters:

work - the work to run. Must not be null.

Returns:

the result of the work.

Throws:

E - if the work throws, in which case the transaction is not committed.

FcPersistenceException - if no transaction is running yet and a new one cannot be opened.

IllegalArgumentException - if the work is null.

E extends Exception

Since:

8.5.6

isTransactionActive

boolean isTransactionActive()

Whether the calling thread runs in a transaction, that is whether it is inside a unit of work.

Returns:

true if the calling thread runs in a transaction.

Since:

8.5.6

markRollbackOnly

void markRollbackOnly()

Prevents the transaction the calling thread runs in from being committed, for work that found a reason not to commit but does not report it as an exception. The unit of work still returns normally.

Throws:

IllegalStateException - if the calling thread does not run in a transaction.

Since:

8.5.6

runInTransaction

<E extends Exception> void runInTransaction(JpaTask<E> work)
                                     throws E extends Exception,
                                            FcPersistenceException

Runs the given work in a transaction.

Type Parameters:

E - the type of the checked exception the work may throw.

Parameters:

work - the work to run. Must not be null.

Throws:

E - if the work throws, in which case the transaction is not committed.

FcPersistenceException - if no transaction is running yet and a new one cannot be opened.

IllegalArgumentException - if the work is null.

E extends Exception

Since:

8.5.6