Package com.ultikits.ultitools.interfaces

Interface TransactionManager

All Known Subinterfaces:

JdbcTransactionManager

All Known Implementing Classes:

DataSourceTransactionManager, JsonTransactionManager

public interface TransactionManager

Interface for managing database transactions.

Implementations handle transaction boundaries (begin, commit, rollback) and provide connections that are aware of the current transaction context.

Since:

6.2.0

Author:

wisdomme

Method Summary

Modifier and Type	Method	Description
void	begin()	Begins a new transaction.
void	commit()	Commits the current transaction.
default Connection	getConnection()	Deprecated, for removal: This API element is subject to removal in a future version. JDBC-specific; not every TransactionManager backs a DataSource.
default Long	getTimeoutDeadlineNanos()	Returns the System.nanoTime() value at which the active transaction's timeout budget expires, or null when no timeout is configured for the active transaction -- no active transaction at all, or @Transactional(timeout=0) (the default).
int	getTransactionDepth()	Gets the current transaction depth (for nested transactions).
boolean	hasActiveTransaction()	Checks if there is an active transaction on the current thread.
default void	resume(Object suspended)	Restores a transaction previously detached by suspend().
void	rollback()	Rolls back the current transaction.
default void	setIsolationLevel(int level)	Deprecated, for removal: This API element is subject to removal in a future version. JDBC-specific; program against JdbcTransactionManager.setIsolationLevel(int) instead.
default void	setReadOnly(boolean readOnly)	Deprecated, for removal: This API element is subject to removal in a future version. JDBC-specific; program against JdbcTransactionManager.setReadOnly(boolean) instead.
void	setTimeout(int seconds)	Sets the timeout for the current transaction.
default Object	suspend()	Suspends the current transaction, if any, detaching it from this thread so an independent transaction can begin in its place.

Method Details

getConnection

@Deprecated(since="6.3.0",
            forRemoval=true)
default Connection getConnection()

Deprecated, for removal: This API element is subject to removal in a future version.

JDBC-specific; not every TransactionManager backs a DataSource. Program against JdbcTransactionManager.getConnection() instead. This default throws UnsupportedOperationException for any backend that only implements the base interface.

Gets the current connection, creating a new one if necessary.

If a transaction is active, returns the connection associated with it. Otherwise, returns a new connection from the data source.

Returns:

the current connection

Since:

6.3.0 demoted from an abstract method to a default one (D-04); zero binary removal.

Scheduled removal version:

6.4.0

begin

void begin()

Begins a new transaction.

Creates a new connection, disables auto-commit, and associates it with the current thread.

Throws:

DataAccessException - if transaction cannot be started

commit

void commit()

Commits the current transaction.

Commits all changes made during the transaction and releases the connection.

Throws:

DataAccessException - if commit fails

rollback

void rollback()

Rolls back the current transaction.

Discards all changes made during the transaction and releases the connection.

hasActiveTransaction

boolean hasActiveTransaction()

Checks if there is an active transaction on the current thread.

Returns:

true if a transaction is active

setIsolationLevel

@Deprecated(since="6.3.0",
            forRemoval=true)
default void setIsolationLevel(int level)

Deprecated, for removal: This API element is subject to removal in a future version.

JDBC-specific; program against JdbcTransactionManager.setIsolationLevel(int) instead. This default throws UnsupportedOperationException for any backend that only implements the base interface.

Sets the isolation level for the current transaction.

Must be called after begin() and before any statements are executed.

Parameters:

level - the JDBC isolation level constant

Since:

6.3.0 demoted from an abstract method to a default one (D-04); zero binary removal.

Scheduled removal version:

6.4.0

setReadOnly

@Deprecated(since="6.3.0",
            forRemoval=true)
default void setReadOnly(boolean readOnly)

Deprecated, for removal: This API element is subject to removal in a future version.

JDBC-specific; program against JdbcTransactionManager.setReadOnly(boolean) instead. This default throws UnsupportedOperationException for any backend that only implements the base interface.

Sets read-only mode for the current transaction.

Parameters:

readOnly - true for read-only mode

Since:

6.3.0 demoted from an abstract method to a default one (D-04); zero binary removal.

Scheduled removal version:

6.4.0

setTimeout

void setTimeout(int seconds)

Sets the timeout for the current transaction.

Note: Not all databases/drivers support transaction timeout.

Parameters:

seconds - the timeout in seconds

getTimeoutDeadlineNanos

default Long getTimeoutDeadlineNanos()

Returns the System.nanoTime() value at which the active transaction's timeout budget expires, or null when no timeout is configured for the active transaction -- no active transaction at all, or @Transactional(timeout=0) (the default).

D-10: consulted per statement (by TimeoutAwareQueryRunner and the two direct PreparedStatement call sites AbstractRelationalDataOperator.insertAll/ updateAll build themselves) to compute the time remaining in the budget, not a value captured once -- the caller re-reads this on every statement.

The default implementation always returns null, meaning "never enforced" -- the same posture a backend whose setTimeout(int) refuses any positive value outright (rather than ever recording a deadline) naturally has, since it never has anything to report here either. A backend that wants per-statement enforcement overrides this together with setTimeout(int) -- overriding only one half of the pair leaves the other silently inert, the same caution suspend()'s javadoc gives for its pair.

Returns:

the deadline, as a System.nanoTime() value, or null if none is active

Since:

6.3.0

getTransactionDepth

int getTransactionDepth()

Gets the current transaction depth (for nested transactions).

Returns:

the transaction depth (0 if no transaction)

suspend

default Object suspend()

Suspends the current transaction, if any, detaching it from this thread so an independent transaction can begin in its place. Backs Propagation.REQUIRES_NEW and Propagation.NOT_SUPPORTED (D-09).

Deliberately typed to return an opaque Object rather than a backend-specific context type: a JDBC-backed manager suspends a Connection-holding context, a JSON snapshot manager (02-05) suspends a set of operator snapshots (D-03) - neither shape belongs on this base interface. Pass whatever this returns to resume(Object) to restore it; the caller must not otherwise inspect or reuse the returned value.

The default implementation does not support suspension: it always returns null, meaning nothing was suspended. A backend that maintains thread-bound transaction state (JDBC, JSON) must override this together with resume(Object) - overriding only one of the pair breaks the contract silently.

Returns:

an opaque handle to resume later, or null if no transaction was active

Since:

6.3.0

resume

default void resume(Object suspended)

Restores a transaction previously detached by suspend().

null is a no-op - it means suspend() found nothing active in the first place, so there is nothing to restore. Passing a handle this TransactionManager did not itself produce is a programming error.

The default implementation is a no-op, pairing with suspend()'s default of always returning null.

Parameters:

suspended - the handle returned by a prior suspend() call, or null

Since:

6.3.0