Class Transactions

java.lang.Object

com.codename1.backend.Transactions

public final class Transactions
extends Object

The transaction a @Transactional method runs in, bound to the calling thread.

The build rewrites every @Transactional method into a call to begin(int, boolean, int), the original body, then commit(Transactions.Transaction) -- or afterThrow(Transactions.Transaction, boolean) with the rollback decision it worked out from the annotation. Propagation, isolation, read-only and timeout arrive as constants. This class binds the connection, completion hooks and scoped resources to the physical transaction on the calling thread.

Joining

Nothing has to be handed the transaction. DataSource.borrow() asks this class first, and a thread inside a transaction gets the transaction's connection back instead of a pooled one -- so the pool's own methods, an EntityManager's daos and a managed session all join it. The connection is borrowed, and BEGIN sent, only when the transaction first needs it: a @Transactional method that returns before touching the database costs only an in-memory scope, with no database round trip.

A thread that has never begun a transaction does not even read the thread-local: used is set by the first begin(int, boolean, int) of the process, on the thread that is then inside it, so every other thread reading a stale false is correct -- none of them is in a transaction.

Propagation

Spring's seven, one for one; the constants below are the ordinals of com.codename1.backend.annotations.Propagation. A method that joins a transaction and fails with a rollback-worthy exception marks the whole transaction rollback-only, and the method that began it then rolls back and throws TransactionException.UnexpectedRollback rather than reporting a commit that did not happen.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	Transactions.Outcome	Final outcome.
static class	Transactions.Synchronization	Hooks run synchronously in registration order, once per physical transaction (including a scope that never borrowed a connection).
static interface	Transactions.Work	A programmatic transaction body.

Method Summary

Modifier and Type	Method	Description
static void	bindResource(Object key, Object value)	Binds a non-null value to a non-null key; duplicate bindings are refused.
static Object	execute(Propagation propagation, boolean readOnly, int timeoutSeconds, Isolation isolation, Transactions.Work work)	Runs a transaction with the same propagation and isolation rules as @Transactional.
static Object	execute(Transactions.Work work)	Runs a REQUIRED transaction with the engine's default isolation.
static Object	getResource(Object key)	Returns the current binding, or null outside a transaction or for a missing key.
static boolean	isActive()	Whether the calling thread is inside a transaction.
static boolean	isRollbackOnly()	Whether the calling thread's transaction has been marked rollback-only.
static void	registerSynchronization(Transactions.Synchronization synchronization)	Registers hooks on the current physical transaction.
static void	setRollbackOnly()	Marks the calling thread's transaction so it rolls back however its method ends -- the programmatic form of throwing, for a method that wants to return a value and still undo its work.
static Object	unbindResource(Object key)	Removes a binding, returning its previous value (or null).

Methods inherited from class Object

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

Method Details

execute

public static Object execute(Transactions.Work work)
                      throws Exception

Runs a REQUIRED transaction with the engine's default isolation.

Throws:

Exception

execute

public static Object execute(Propagation propagation,
 boolean readOnly,
 int timeoutSeconds,
 Isolation isolation,
 Transactions.Work work)
                      throws Exception

Runs a transaction with the same propagation and isolation rules as @Transactional. Unlike annotation rollback rules, every body failure rolls back.

Throws:

Exception

registerSynchronization

public static void registerSynchronization(Transactions.Synchronization synchronization)

Registers hooks on the current physical transaction. Registration is closed when completion begins. A rolled-back NESTED scope suppresses its before/after-commit hooks, but its completion hook still runs at physical end.

bindResource

public static void bindResource(Object key,
 Object value)

Binds a non-null value to a non-null key; duplicate bindings are refused. Bindings belong to the physical transaction, not to a savepoint. They are cleared after all completion hooks; dispose values in afterCompletion.

getResource

public static Object getResource(Object key)

Returns the current binding, or null outside a transaction or for a missing key. Bindings remain visible to completion callbacks until all have finished.

unbindResource

public static Object unbindResource(Object key)

Removes a binding, returning its previous value (or null).

isActive

public static boolean isActive()

Whether the calling thread is inside a transaction.

isRollbackOnly

public static boolean isRollbackOnly()

Whether the calling thread's transaction has been marked rollback-only.

setRollbackOnly

public static void setRollbackOnly()

Marks the calling thread's transaction so it rolls back however its method ends -- the programmatic form of throwing, for a method that wants to return a value and still undo its work.