Class Transactions

java.lang.Object
com.codename1.backend.Transactions
public final class Transactions extends Object

The transaction a @Transactional method runs in, bound to the calling thread.

The build rewrites every @Transactional method into a call to begin(int, boolean, int), the original body, then commit(Transactions.Transaction) -- or afterThrow(Transactions.Transaction, boolean) with the rollback decision it worked out from the annotation. The propagation, the read-only flag and the timeout arrive as constants, so this class interprets nothing: it holds the one piece of state that has to exist at run time, which is which connection the thread's transaction is on.

Joining

Nothing has to be handed the transaction. DataSource.borrow() asks this class first, and a thread inside a transaction gets the transaction's connection back instead of a pooled one -- so the pool's own methods, an EntityManager's daos and a managed session all join it. The connection is borrowed, and BEGIN sent, only when the transaction first needs it: a @Transactional method that returns before touching the database costs a thread-local write and nothing else.

A thread that has never begun a transaction does not even read the thread-local: used is set by the first begin(int, boolean, int) of the process, on the thread that is then inside it, so every other thread reading a stale false is correct -- none of them is in a transaction.

Propagation

Spring's seven, one for one; the constants below are the ordinals of com.codename1.backend.annotations.Propagation. A method that joins a transaction and fails with a rollback-worthy exception marks the whole transaction rollback-only, and the method that began it then rolls back and throws TransactionException.UnexpectedRollback rather than reporting a commit that did not happen.

  • Field Details

  • Method Details

    • isActive

      public static boolean isActive()
      Whether the calling thread is inside a transaction.

    • isRollbackOnly

      public static boolean isRollbackOnly()
      Whether the calling thread's transaction has been marked rollback-only.

    • setRollbackOnly

      public static void setRollbackOnly()
      Marks the calling thread's transaction so it rolls back however its method ends -- the programmatic form of throwing, for a method that wants to return a value and still undo its work.

    • begin

      public static Transactions.Transaction begin(int propagation, boolean readOnly, int timeoutSeconds)

      Starts what a @Transactional method asked for. Called by woven code.

      Parameters

      • propagation: one of the constants above

      • readOnly: the annotation's readOnly

      • timeoutSeconds: the annotation's timeout, zero or less for none

    • commit

      public static void commit(Transactions.Transaction tx)
      Ends a call that returned normally. Commits when the call began the transaction, and does nothing more than restore state when it joined one.

    • afterThrow

      public static void afterThrow(Transactions.Transaction tx, boolean rollback)

      Ends a call that threw. Rolls back -- the call's own transaction, its savepoint, or, when it joined one, by marking the shared transaction rollback-only -- when rollback is true, and otherwise treats the exception as a normal end, which is Spring's rule for a checked one.

      Never throws: the woven code rethrows the method's own exception after this returns, and a failure here would replace the cause with a symptom. A rollback that fails is reported on standard error and its connection closed, so the pool cannot hand out a session that is still inside a transaction.

    • joined

      public static Database joined(DataSource pool) throws IOException
      The transaction's connection for pool, borrowing it and sending BEGIN the first time; null when the thread is not in a transaction or its transaction is on another database. Called by DataSource.borrow().
      Throws:
      IOException

    • isJoined

      public static boolean isJoined(DataSource pool, Database db)
      Whether db is the connection of the calling thread's transaction on pool.

    • isActiveOn

      public static boolean isActiveOn(DataSource pool)
      Whether the calling thread's transaction is on pool, or could be.

    • session

      public static Session session(EntityManager entities)

      The managed session of the calling thread's transaction, opened on the transaction's connection the first time it is asked for and flushed and closed when the transaction ends.

      This is what an injected Session delegates to. Outside a transaction there is no session to give, and the refusal says where one comes from.

    • markRollbackOnly

      public static void markRollbackOnly()
      Called by the session adapter when a session that joined this thread's transaction rolls back: the rows are not the session's to keep, so the transaction they are in cannot commit either. Marks the calling thread's transaction, whatever pool it is on, as unable to commit; nothing when there is none.

    • markRollbackOnly

      public static void markRollbackOnly(DataSource pool)