st.orm.template.Transactions

public final class Transactions extends Object

Programmatic transactions for Java.

The transaction binds to the first ORM template that executes inside the block: opening the block only records the requested options, and the template's transaction provider opens the actual transaction on first use. A block that never touches a template completes as a no-op. The block commits when it completes normally and rolls back when it throws; checked exceptions propagate to the caller unchanged.

import static st.orm.template.Transactions.transaction;
import static st.orm.TransactionPropagation.REQUIRES_NEW;

var user = transaction(tx -> users.insertAndFetch(user));

transaction(REQUIRES_NEW, tx -> {
    tx.onCommit(() -> log.info("audit committed"));
    return audit.insertAndFetch(entry);
});

// Runs up to three times when an attempt fails with a deadlock or a serialization failure.
transaction(2, tx -> accounts.update(account));

The transaction subsystem is provider-driven: standalone templates run on Storm's JDBC transactions, and templates composed with an integration's providers (such as Spring's) run through that platform's transaction manager — the calling code is identical.

All entry points are blocking and virtual-thread friendly: the block parks on I/O rather than pinning carrier threads.

## Propagation behavior matrix

Propagation behavior
Propagation	Inner commit	Inner rollback	Outer commit	Outer rollback
`REQUIRED`	Joins outer tx — no actual commit until outer ends	Marks whole tx rollback-only; everything rolls back at end	Commits entire tx (all work)	Rolls back entire tx (all work)
`REQUIRES_NEW`	Commits only the new (inner) tx	Rolls back only the inner tx; outer stays active	Commits the outer tx (inner work stays committed)	Rolls back the outer tx; inner-committed work remains
`NESTED`	Releases the JDBC savepoint — inner changes become visible to the outer transaction	Rolls back to savepoint — undoes just inner work, outer stays open	Commits entire tx (savepoints dropped, all work kept)	Rolls back entire tx (including inner work, regardless of savepoint)

Since:: 1.13

Method Summary

Modifier and Type

Method

Description

static void

setGlobalTransactionOptions(TransactionOptions options)

Sets the global transaction options, affecting new transactions that do not override options locally.

static <R extends @Nullable Object, E extends Exception> R

transaction(int retries, TransactionBlock<R,E> block)

Executes the given block within a database transaction with the surrounding default options, running it again, up to retries times, after an attempt that failed transiently.

static <R extends @Nullable Object, E extends Exception> R

transaction(TransactionBlock<R,E> block)

Executes the given block within a database transaction with the surrounding default options.

static <R extends @Nullable Object, E extends Exception> R

transaction(TransactionOptions options, int retries, TransactionBlock<R,E> block)

Executes the given block within a database transaction with the given options, running it again, up to retries times, after an attempt that failed transiently.

static <R extends @Nullable Object, E extends Exception> R

transaction(TransactionOptions options, TransactionBlock<R,E> block)

Executes the given block within a database transaction with the given options.

static <R extends @Nullable Object, E extends Exception> R

transaction(TransactionPropagation propagation, int retries, TransactionBlock<R,E> block)

Executes the given block within a database transaction with the given propagation, running it again, up to retries times, after an attempt that failed transiently.

static <R extends @Nullable Object, E extends Exception> R

transaction(TransactionPropagation propagation, TransactionBlock<R,E> block)

Executes the given block within a database transaction with the given propagation.

static <R extends @Nullable Object, E extends Exception> R

withTransactionOptions(TransactionOptions options, TransactionSupplier<R,E> block)

Executes the given block with the given options as the thread-scoped transaction defaults.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details
- transaction
  
  public static <R extends @Nullable Object, E extends Exception> R transaction(TransactionBlock<R,E> block) throws E
  
  Executes the given block within a database transaction with the surrounding default options.
  
  Type Parameters:
  
  R - the result type.
  
  E - the checked exception type thrown by the block, if any.
  
  Parameters:
  
  block - the transactional logic to execute.
  
  Returns:
  
  the result of the block.
  
  Throws:
  
  PersistenceException - if transaction execution fails.
  
  E
- transaction
  
  public static <R extends @Nullable Object, E extends Exception> R transaction(TransactionPropagation propagation, TransactionBlock<R,E> block) throws E
  
  Executes the given block within a database transaction with the given propagation.
  
  Type Parameters:
  
  R - the result type.
  
  E - the checked exception type thrown by the block, if any.
  
  Parameters:
  
  propagation - how the block relates to an already active transaction.
  
  block - the transactional logic to execute.
  
  Returns:
  
  the result of the block.
  
  Throws:
  
  PersistenceException - if transaction execution fails.
  
  E
- transaction
  
  public static <R extends @Nullable Object, E extends Exception> R transaction(TransactionOptions options, TransactionBlock<R,E> block) throws E
  
  Executes the given block within a database transaction with the given options. Options left null are inherited from the surrounding defaults: the thread-scoped options, then the global options, then the baseline (TransactionPropagation.REQUIRED, provider-default isolation and timeout, read-write).
  
  Type Parameters:
  
  R - the result type.
  
  E - the checked exception type thrown by the block, if any.
  
  Parameters:
  
  options - the transaction options.
  
  block - the transactional logic to execute.
  
  Returns:
  
  the result of the block.
  
  Throws:
  
  PersistenceException - if transaction execution fails.
  
  E
- transaction
  
  public static <R extends @Nullable Object, E extends Exception> R transaction(int retries, TransactionBlock<R,E> block) throws E
  
  Executes the given block within a database transaction with the surrounding default options, running it again, up to retries times, after an attempt that failed transiently.
  Type Parameters:
  
  R - the result type.
  
  E - the checked exception type thrown by the block, if any.
  
  Parameters:
  
  retries - the number of reruns after the first attempt; 0 runs the block once.
  
  block - the transactional logic to execute.
  
  Returns:
  
  the result of the attempt that committed.
  
  Throws:
  
  IllegalTransactionStateException - if retries is positive and the block does not start its own transaction.
  
  PersistenceException - if transaction execution fails.
  
  E
  
  Since:
  
  1.16
  
  See Also:
  
  transaction(TransactionOptions, int, TransactionBlock)
- transaction
  
  public static <R extends @Nullable Object, E extends Exception> R transaction(TransactionPropagation propagation, int retries, TransactionBlock<R,E> block) throws E
  
  Executes the given block within a database transaction with the given propagation, running it again, up to retries times, after an attempt that failed transiently.
  Type Parameters:
  
  R - the result type.
  
  E - the checked exception type thrown by the block, if any.
  
  Parameters:
  
  propagation - how the block relates to an already active transaction.
  
  retries - the number of reruns after the first attempt; 0 runs the block once.
  
  block - the transactional logic to execute.
  
  Returns:
  
  the result of the attempt that committed.
  
  Throws:
  
  IllegalTransactionStateException - if retries is positive and the block does not start its own transaction.
  
  PersistenceException - if transaction execution fails.
  
  E
  
  Since:
  
  1.16
  
  See Also:
  
  transaction(TransactionOptions, int, TransactionBlock)
- transaction
  
  public static <R extends @Nullable Object, E extends Exception> R transaction(TransactionOptions options, int retries, TransactionBlock<R,E> block) throws E
  
  Executes the given block within a database transaction with the given options, running it again, up to retries times, after an attempt that failed transiently. Options left null are inherited from the surrounding defaults, as with transaction(TransactionOptions, TransactionBlock); the retry count is never inherited and holds for this block alone.
  An attempt reruns only when it failed transiently, as the framework classified the failure: a deadlock, a serialization failure or an optimistic lock conflict, whatever type the template's exception mapper translates it to. Every other failure leaves the block on the attempt it occurred in. Each attempt is a transaction of its own: the timeout counts from the start of the attempt, and the callbacks an attempt registered fire by that attempt's outcome, so onCommit runs only for the attempt that committed. Between attempts the thread sleeps for a short, jittered pause that grows per attempt; an interrupt ends the reruns. When the last attempt fails, its failure leaves the block with the earlier attempts' failures as suppressed.
  
  A rerun starts the transaction over, so the block must start its own: REQUIRES_NEW, or REQUIRED or NESTED while no transaction is active. A block that joins an active transaction, including one an external transaction manager owns, or runs without one is refused at its start with an IllegalTransactionStateException when retries is positive.
  
  A block that may be rerun touches nothing outside the database except through onCommit.
  
  Type Parameters:
  
  R - the result type.
  
  E - the checked exception type thrown by the block, if any.
  
  Parameters:
  
  options - the transaction options.
  
  retries - the number of reruns after the first attempt; 0 runs the block once.
  
  block - the transactional logic to execute.
  
  Returns:
  
  the result of the attempt that committed.
  
  Throws:
  
  IllegalArgumentException - if retries is negative.
  
  IllegalTransactionStateException - if retries is positive and the block does not start its own transaction.
  
  PersistenceException - if transaction execution fails.
  
  E
  
  Since:
  
  1.16
- setGlobalTransactionOptions
  
  public static void setGlobalTransactionOptions(TransactionOptions options)
  
  Sets the global transaction options, affecting new transactions that do not override options locally. Options left null fall back to the baseline defaults.
  Typical usage: call once during application startup to configure defaults that apply to all transactions.
  
  Parameters:
  
  options - the global transaction options.
- withTransactionOptions
  
  public static <R extends @Nullable Object, E extends Exception> R withTransactionOptions(TransactionOptions options, TransactionSupplier<R,E> block) throws E
  
  Executes the given block with the given options as the thread-scoped transaction defaults. Options left null inherit the current defaults; the previous defaults are restored when the block completes.
  
  Type Parameters:
  
  R - the result type.
  
  E - the checked exception type thrown by the block, if any.
  
  Parameters:
  
  options - the scoped transaction defaults.
  
  block - the code to execute.
  
  Returns:
  
  the result of the block.
  
  Throws:
  
  E

Class Transactions

Method Summary

Methods inherited from class java.lang.Object

Method Details

transaction

transaction

transaction

transaction

transaction

transaction

setGlobalTransactionOptions

withTransactionOptions