Module storm.foundation

Package st.orm

Interface Transaction

public interface Transaction

Handle to the transaction a transactional block runs in: exposes the rollback-only state and registration of completion callbacks.

This is the language-neutral base handle. The Kotlin API extends it with suspend-friendly callback overloads.

Since:

1.13

Method Summary

Modifier and Type	Method	Description
boolean	isRollbackOnly()	Whether the transaction is marked rollback-only.
void	onCommit(Runnable callback)	Registers a callback invoked after the physical transaction commits successfully.
void	onCompletion(Consumer<Boolean> callback)	Registers a callback invoked after the physical transaction completes, whichever way it completed.
void	onRollback(Runnable callback)	Registers a callback invoked after the physical transaction rolls back.
void	setRollbackOnly()	Marks the transaction rollback-only: the block completes normally, but the transaction rolls back.

Method Details

isRollbackOnly

boolean isRollbackOnly()

Whether the transaction is marked rollback-only.

setRollbackOnly

void setRollbackOnly()

Marks the transaction rollback-only: the block completes normally, but the transaction rolls back.

onCommit

void onCommit(Runnable callback)

Registers a callback invoked after the physical transaction commits successfully.

If this scope is joined to an outer transaction (for example via TransactionPropagation.REQUIRED or TransactionPropagation.NESTED), the callback is deferred to the outermost physical transaction's commit. TransactionPropagation.REQUIRES_NEW scopes fire their own callbacks independently.

The scope is uninstalled before the callback runs, so no transaction is active while it executes. A database operation performed here runs in auto-commit, and a transactional block opened here starts a new physical transaction rather than joining the one that just committed. That is what makes the callback the place for work that must observe the committed state, or that must not be rolled back together with it, such as publishing an event or invalidating a cache.

Callbacks run synchronously, before the transactional block returns, so their duration is added to the caller's. Work that can block for a long time, such as a write that contends with a batch job, belongs on a background worker that the callback hands off to.

Callbacks registered through onCommit(Runnable), onRollback(Runnable) and onCompletion(Consumer) share one order: they execute in the order they were registered, skipping the ones that do not apply to the outcome. If a callback throws, remaining callbacks still execute and the failures are reported as a TransactionCallbackException whose cause is the first one, with the rest attached to it as suppressed. That exception leaves the transactional block after the transaction has already committed, so catch it to tell a failed side effect apart from a failed transaction.

Parameters:

callback - the callback to invoke after commit.

onRollback

void onRollback(Runnable callback)

Registers a callback invoked after the physical transaction rolls back.

Rollback may be triggered by an exception, setRollbackOnly(), or a timeout. Deferral, ordering, exception handling, and the absence of an active transaction while the callback runs match onCommit(Runnable). When the rollback was caused by an exception, a callback failure is attached to that exception as suppressed rather than replacing it.

Parameters:

callback - the callback to invoke after rollback.

onCompletion

void onCompletion(Consumer<Boolean> callback)

Registers a callback invoked after the physical transaction completes, whichever way it completed. The callback receives true when the transaction committed and false when it rolled back.

This is the variant for work that has to happen either way, such as releasing a lock or closing a span. Use onCommit(Runnable) or onRollback(Runnable) when only one outcome is of interest; they are the simpler form and say so at the registration site.

Deferral, ordering, exception handling, and the absence of an active transaction while the callback runs match onCommit(Runnable).

Parameters:

callback - the callback to invoke after completion.