Package com.ultikits.ultitools.manager

Class DataSourceTransactionManager

java.lang.Object
com.ultikits.ultitools.manager.DataSourceTransactionManager
All Implemented Interfaces:
JdbcTransactionManager, TransactionManager
@Internal public class DataSourceTransactionManager extends Object implements JdbcTransactionManager
DataSource-based implementation of TransactionManager, and its JDBC-specific sub-interface JdbcTransactionManager.

Uses ThreadLocal to associate transactions with threads, ensuring thread safety. Each thread can have at most one active transaction at a time.

No further commit is issued for a transaction whose commit or rollback failed (as of 6.3.0, UltiTools-Reborn#634): auto-commit is never switched on for it, and the commit is never retried. JDBC commits an open transaction when auto-commit is switched on (Connection.setAutoCommit(boolean)), so auto-commit is restored only after a commit or rollback that succeeded. A connection whose commit or rollback failed is discarded instead: a HikariCP pool is told to evict it (HikariDataSource.evictConnection(Connection), which closes the physical connection, and the database rolls the open transaction back), and any other connection is closed. Returning a connection after a failed rollback risks letting the next borrower join an unresolved transaction; explicit eviction ensures that connection is never handed out again.

What the caller can rely on afterwards (this class serves SQLite and MySQL):

  • A rollback that succeeded is the confirmed outcome: none of the transaction's writes is stored.
  • A commit that finds the transaction marked rollback-only rolls it back and throws UnexpectedRollbackException: a confirmed rollback, none of its writes stored. If that rollback fails, the connection is discarded and nothing is committed either.
  • After a failed rollback, the connection is discarded and the framework issues no commit.
  • After a commit that fails at Connection.commit() (DataAccessException, TRANSACTION_FAILED), the outcome is unknown. The database may have applied the commit before the failure reached the framework (for example, a MySQL connection lost after COMMIT executed and before its acknowledgement arrived), and discarding or evicting the connection cannot undo an applied commit. A caller that must not apply a write twice re-reads the data, or makes the write conditional, before trying again.
Since:
6.2.0
Author:
wisdomme

  • Field Details

  • Constructor Details

    • DataSourceTransactionManager

      public DataSourceTransactionManager(DataSource dataSource)
      Creates a new DataSourceTransactionManager.
      Parameters:
      dataSource - the data source to use for connections

  • Method Details

    • getConnection

      public Connection getConnection()
      Description copied from interface: JdbcTransactionManager
      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.

      Specified by:
      getConnection in interface JdbcTransactionManager
      Specified by:
      getConnection in interface TransactionManager
      Returns:
      the current connection

    • begin

      public void begin()
      Description copied from interface: TransactionManager
      Begins a new transaction.

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

      Specified by:
      begin in interface TransactionManager

    • commit

      public void commit()
      Commits the current transaction.

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

      What a failed commit means depends on the implementation:

      • For the JDBC implementation used by SQLite and MySQL (DataSourceTransactionManager), a DataAccessException (TRANSACTION_FAILED) raised because Connection.commit() failed leaves the outcome unknown: the database may have applied the commit before the failure reached the framework.
      • For the JSON implementation (JsonTransactionManager), a failed commit commits nothing, as its commit() javadoc states.
      • On every implementation, an UnexpectedRollbackException means the transaction had been marked rollback-only and was rolled back: none of its writes was stored.
      Implementations do not retry the commit. A caller that must not apply a write twice re-reads the data, or makes the write conditional (DataOperator#updateIf), before trying again after an unknown outcome.

      An UnexpectedRollbackException means the transaction had been marked rollback-only and was rolled back: none of its writes is stored. A DataAccessException (TRANSACTION_FAILED) raised because Connection.commit() failed means the outcome is unknown: the database may have applied the commit before the failure reached the framework, and discarding the connection cannot undo that. Either way the transaction has ended, its connection is never switched to auto-commit, and the commit is not retried.

      Specified by:
      commit in interface TransactionManager

    • rollback

      public void rollback()
      Description copied from interface: TransactionManager
      Rolls back the current transaction.

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

      Specified by:
      rollback in interface TransactionManager

    • hasActiveTransaction

      public boolean hasActiveTransaction()
      Description copied from interface: TransactionManager
      Checks if there is an active transaction on the current thread.
      Specified by:
      hasActiveTransaction in interface TransactionManager
      Returns:
      true if a transaction is active

    • setIsolationLevel

      public void setIsolationLevel(int level)
      Description copied from interface: JdbcTransactionManager
      Sets the isolation level for the current transaction.

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

      Specified by:
      setIsolationLevel in interface JdbcTransactionManager
      Specified by:
      setIsolationLevel in interface TransactionManager
      Parameters:
      level - the JDBC isolation level constant

    • setReadOnly

      public void setReadOnly(boolean readOnly)
      Description copied from interface: JdbcTransactionManager
      Sets read-only mode for the current transaction.
      Specified by:
      setReadOnly in interface JdbcTransactionManager
      Specified by:
      setReadOnly in interface TransactionManager
      Parameters:
      readOnly - true for read-only mode

    • setTimeout

      public void setTimeout(int seconds)
      Sets the timeout for the current transaction.

      Note: Not all databases/drivers support transaction timeout.

      D-10: records a deadline on the active DataSourceTransactionManager.TransactionContext rather than a wall-clock bound on the transaction as a whole -- getTimeoutDeadlineNanos() exposes it so each statement issued afterward can be given the time remaining, not a fresh full allowance. seconds <= 0 is inert (no deadline recorded), matching @Transactional(timeout=0)'s default -- TransactionInterceptor itself never calls this method for a non-positive value in the first place, so this is a second, defensive guard for any other caller. Called with no active transaction, this logs a warning and records nothing, the same shape commit()/rollback() already use for that case.

      Specified by:
      setTimeout in interface TransactionManager
      Parameters:
      seconds - the timeout in seconds

    • getTimeoutDeadlineNanos

      public 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 TransactionManager.setTimeout(int) -- overriding only one half of the pair leaves the other silently inert, the same caution TransactionManager.suspend()'s javadoc gives for its pair.

      Reads DataSourceTransactionManager.TransactionContext.timeoutDeadlineNanos off the active context -- null when no transaction is active, or when setTimeout(int) was never called (or called only with a non-positive value) for it. suspend()/resume(Object) detach and restore the whole DataSourceTransactionManager.TransactionContext object, so a suspended-then-resumed transaction's deadline travels with it automatically -- no separate handling needed here.

      Specified by:
      getTimeoutDeadlineNanos in interface TransactionManager
      Returns:
      the deadline, as a System.nanoTime() value, or null if none is active

    • getTransactionDepth

      public int getTransactionDepth()
      Description copied from interface: TransactionManager
      Gets the current transaction depth (for nested transactions).
      Specified by:
      getTransactionDepth in interface TransactionManager
      Returns:
      the transaction depth (0 if no transaction)

    • suspend

      public 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, the JSON manager suspends the transaction's context, which carries its staged writes and its table lock holds - neither shape belongs on this base interface. Pass whatever this returns to TransactionManager.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 TransactionManager.resume(Object) - overriding only one of the pair breaks the contract silently.

      Detaches the current DataSourceTransactionManager.TransactionContext (connection included) from this thread and pushes it onto suspendedStack, leaving hasActiveTransaction() false. A begin() that runs while the original stays suspended opens a fully independent transaction, on its own connection - the suspended one is never touched until resume(Object) restores it.

      Specified by:
      suspend in interface TransactionManager
      Returns:
      an opaque handle to resume later, or null if no transaction was active

    • resume

      public void resume(Object suspended)
      Restores a transaction previously detached by TransactionManager.suspend().

      null is a no-op - it means TransactionManager.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 TransactionManager.suspend()'s default of always returning null.

      null is a no-op - suspend() found nothing active in the first place, so there is nothing on suspendedStack for this call to pop. A non-null handle must be exactly what this manager's own suspend() most recently returned; restoring it sets it back as the active context (same DataSourceTransactionManager.TransactionContext instance, same Connection, same depth) and pops it off suspendedStack, removing the ThreadLocal entirely once the stack is empty rather than leaving a dangling empty Deque behind.

      Specified by:
      resume in interface TransactionManager
      Parameters:
      suspended - the handle returned by a prior TransactionManager.suspend() call, or null
      Throws:
      IllegalArgumentException - if suspended is non-null but was not produced by this manager's own suspend()

    • cleanup

      private void cleanup(DataSourceTransactionManager.TransactionContext ctx, boolean completed)
      Ends the transaction context: removes it from this thread and never throws.

      completed -- the commit or rollback succeeded: auto-commit is restored and the connection closed (back to the pool). Otherwise the connection is discarded through discardConnection(DataSource, Connection) and auto-commit is never switched on (#634).

      Parameters:
      ctx - the context to end
      completed - whether its commit or rollback succeeded

    • discardConnection

      @Internal public static void discardConnection(DataSource dataSource, Connection connection)
      Discards a connection whose commit or rollback failed, without ever switching auto-commit on (UltiTools-Reborn#634): JDBC commits an open transaction when auto-commit is switched on. When dataSource is, or wraps, a HikariDataSource and connection is one of its connections, the pool evicts it -- the physical connection is closed, the database rolls the open transaction back, and the connection is never handed out again; the caller must not use it afterwards. Any other connection is closed. Never throws; a failure is logged.
      Parameters:
      dataSource - the data source connection came from, possibly null
      connection - the connection to discard, possibly null
      Since:
      6.3.0

    • hikariPool

      private static com.zaxxer.hikari.HikariDataSource hikariPool(DataSource dataSource)

    • getCurrentContext

      DataSourceTransactionManager.TransactionContext getCurrentContext()
      Gets the current transaction context (for testing).

      Instance method, not static, per the same FOUND-04 fix as contextHolder itself: two DataSourceTransactionManager instances now have independent state.