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
    void
    cancel()
    Cancels the transaction: the statement the block is blocked on is stopped through the driver, and no further statement runs in the block.
    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.

    • cancel

      void cancel()
      Cancels the transaction: the statement the block is blocked on is stopped through the driver, and no further statement runs in the block. The block then fails at that statement, or at its next one, and rolls back as a failing block does. A cancellation states no further interest in the block's work, not an outcome: a block whose statements all completed before it arrived completes as usual.

      Meant to be called from another thread or coroutine, by whoever decides the work is no longer wanted: the block hands its handle out, and the caller returns at once while the driver is asked to stop the statement on a thread of its own. The block may also call it on itself, which refuses its next statement. A suspending block is cancelled the same way when its coroutine is cancelled.

      Since:
      1.16

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