Transaction API

This page defines the supported programmatic API in io.kaumei.jdbc.tx. Propagation and completion behaviour are defined by Transaction Semantics.

Supported API boundary

Application code may use the public types declared directly in io.kaumei.jdbc.tx. io.kaumei.jdbc.tx.internal is an internal implementation package and is not part of the supported public API. Its classes may change or be removed without compatibility guarantees.

InterfaceWrapper and TransactionInterceptors are internal test infrastructure even though their Java declarations are currently public. They are not application integration APIs.

Construction

❗️Manager construction

KaumeiTxManager.getInstance(JdbcConnectionProvider) is the default construction entry point. Each call creates a new manager and returns it as KaumeiTxManager. The concrete implementation is not part of the public contract.

The provider is required. A null provider causes NullPointerException.

Transaction definition

❗️Transaction definition❗️Annotation conversion

KaumeiTxDefinition contains every non-propagation attribute:

Component	Default
isolation	Isolation.DEFAULT
readOnly	ReadOnly.DEFAULT
rollbackOn	NO_THROWABLES
dontRollbackOn	NO_THROWABLES

KaumeiTxDefinition.DEFAULT contains these four values. KaumeiTxDefinition.builder().build() is semantically equal to DEFAULT. KaumeiTxDefinition.from(KaumeiTx) converts the annotation’s isolation, read-only, and rollback attributes into a programmatic definition. It returns the shared DEFAULT instance when all definition attributes use their defaults; the annotation’s transaction type is handled separately.

NO_THROWABLES matches no Throwable. ALL_THROWABLES matches every Throwable, including Exception and Error. ExceptionMatcher receives the thrown Throwable and is the supported matcher type; Predicate<Throwable> is not used.

Each builder method replaces only its corresponding value and returns the same builder. build() creates an immutable definition from the current values. Null record components and null builder arguments cause NullPointerException.

Isolation, read-only, and rollback evaluation are defined by Transaction Semantics.

Callback methods

❗️Callback overloads

Deliberate difference from Jakarta Transactions

Kaumei uses scoped callbacks instead of manual transaction boundaries and checked SystemException handling. Programmatic and declarative transaction handling delegate to the same callback API.

The manager method name selects the transaction type:

Method family	Transaction type
required / requiredOpt	REQUIRED
requiresNew / requiresNewOpt	REQUIRES_NEW
mandatory / mandatoryOpt	MANDATORY
supports / supportsOpt	SUPPORTS
notSupported / notSupportedOpt	NOT_SUPPORTED
never / neverOpt	NEVER

Each family accepts a KaumeiTxDefinition and one callback form:

Callback	Result contract
Callback	Returns no value
CallbackWithResult<T>	Returns a non-null value
CallbackWithNullableResult<T> through an *Opt method	May return null

Every invoked callback receives a non-null KaumeiTxContext. Context selection and lifetime are defined by the Transaction Manager.

Definitions and callbacks are required. A null argument causes NullPointerException. Callbacks may throw checked exceptions.

Callback results

A non-null callback overload validates its result after the selected transaction scope returns. When that call owns a transaction, validation occurs after transaction completion and therefore after commit or rollback. If the result is null, the manager then throws NullPointerException("result"). The null result is not a callback failure and does not alter the transaction outcome.

Only the *Opt overloads permit a null result.

Transaction state operations

❗️Transaction state operations

isTransactionActive() reports whether the current context is active. It returns false for a terminal FINISHED context awaiting cleanup.

setRollbackOnly() and isRollbackOnly() require an active transaction. setRollbackOnly() is idempotent.

registerSynchronization(...) requires an active transaction whose completion has not started. commitAndContinue() requires an active transaction in state RUNNING.

The same requirements apply to the corresponding KaumeiTxContext operations. Invalid state causes IllegalStateException and null arguments cause NullPointerException.

There is no public final commit() or rollback() operation. Intermediate completion is defined by Transaction Semantics.

Synchronisation

❗️Synchronisation

Deliberate difference from Jakarta Transactions

Kaumei uses typed before- and after-completion status enums. beforeCompletion(...) runs before every completion attempt, receives the current completion intent, and may request rollback by returning ROLLING_BACK.

KaumeiTxSynchronization provides independently optional callbacks:

default BeforeStatus beforeCompletion(BeforeStatus status) {
    return status;
}

default void afterCompletion(AfterStatus status) {
}

An implementation may override neither, either, or both methods. The default beforeCompletion(...) preserves the current status and the default afterCompletion(...) has no effect.

Synchronisations may request rollback and observe completion. They do not intercept, replace, or wrap the physical JDBC commit or rollback operation.

Registration order defines the order of both callbacks. Duplicate registration is allowed and invokes the synchronization once for each registration. A registration applies to exactly one completion attempt and is removed after afterCompletion, including after an intermediate commit.

Before completion

beforeCompletion(...) runs once for every registered callback before every intermediate or final completion attempt. It runs with the transaction context active.

Status or result	Meaning or effect
COMMITTING	Commit is currently intended
ROLLING_BACK	Rollback is already required
Return COMMITTING	Preserve the current intent; it cannot cancel rollback
Return ROLLING_BACK	Mark rollbackOnly and pass ROLLING_BACK to the next callback

An existing rollbackOnly state or a failure requiring rollback starts with ROLLING_BACK. Calling setRollbackOnly(), returning ROLLING_BACK, or throwing from the callback makes rollback intent sticky. Remaining callbacks always run with the current status.

After completion

afterCompletion(...) runs once for every registered callback after every completion attempt.

Status	Outcome
COMMITTED	The physical commit succeeded
ROLLED_BACK	The physical rollback succeeded
UNKNOWN	Completion did not produce a reliable commit or rollback outcome

It runs without the completed transaction context. A callback failure does not change the status or prevent remaining callbacks from running.

Before- and after-completion failures follow the primary and suppressed failure rules defined by Transaction Semantics.

Failure surface

Invalid transaction state causes IllegalStateException. Transaction-manager failures use unchecked KaumeiTxException. Checked callback failures are propagated with their identity preserved.

The propagation-specific manager methods remain visible in failure stack traces. The exact stack-trace layout is not an API compatibility guarantee.