Module storm.java
Package st.orm.template

Class Transactions

java.lang.Object
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);
});

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
PropagationInner commitInner rollbackOuter commitOuter rollback
REQUIREDJoins 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_NEWCommits 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
NESTEDReleases 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 Details

    • transaction

      public static <R, 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, 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, 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

    • 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, 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