Package io.quarkus.narayana.jta

Interface QuarkusTransaction

public interface QuarkusTransaction
A simplified transaction interface. While broadly covering the same use cases as UserTransaction, this class is designed to be easier to use. The main features it offers over UserTransaction are:
  • No Checked Exceptions: All underlying checked exceptions are wrapped in an unchecked QuarkusTransactionException.
  • No Transaction Leaks: Transactions are tied to the request scope, if the scope is destroyed before the transaction is committed the transaction is rolled back. Note that this means this can only currently be used when the request scope is active.
  • Per Transaction Timeouts: {BeginOptions.timeout(int)/TransactionRunnerOptions.timeout(int) can be used to set the new transactions timeout, without affecting the per thread default.
  • Lambda Style Transactions: Runnable and Callable instances can be run inside the scope of a new transaction.

Note that any checked exception will be wrapped by a QuarkusTransactionException, while unchecked exceptions are allowed to propagate unchanged.

  • Method Details

    • begin

      static void begin()
      Starts a transaction, using the system default timeout.

      This transaction will be tied to the current request scope, if it is not committed when the scope is destroyed then it will be rolled back to prevent transaction leaks.

    • begin

      static void begin(BeginOptions options)
      Starts a transaction, using the system default timeout.

      This transaction will be tied to the current request scope, if it is not committed when the scope is destroyed then it will be rolled back to prevent transaction leaks.

      Parameters:
      options - Options that apply to the new transaction

    • commit

      static void commit()
      Commits the current transaction.

    • rollback

      static void rollback()
      Rolls back the current transaction.

    • isActive

      static boolean isActive()
      If a transaction is active.
      Returns:
      true if the transaction is active.

    • isRollbackOnly

      static boolean isRollbackOnly()
      If the transaction is rollback only
      Returns:
      If the transaction has been marked for rollback

    • setRollbackOnly

      static void setRollbackOnly()
      Marks the transaction as rollback only. Operations can still be carried out, however the transaction cannot be successfully committed.

    • joiningExisting

      static TransactionRunnerOptions joiningExisting()
      Starts the definition of a transaction runner, which can then be used to run a task (Runnable, Callable, ...), with TransactionSemantics.JOIN_EXISTING semantics:
      • If no transaction is active then a new transaction will be started, and committed when the method ends.
      • If an exception is thrown the exception handler registered by TransactionRunnerOptions.exceptionHandler(Function) will be called to decide if the TX should be committed or rolled back.
      • If an existing transaction is active then the method is run in the context of the existing transaction. If an exception is thrown the exception handler will be called, however a result of TransactionExceptionResult.ROLLBACK will result in the TX marked as rollback only, while a result of TransactionExceptionResult.COMMIT will result in no action being taken.

      Examples of use: 

      
 QuarkusTransaction.joiningExisting().run(() -> ...);
 int value = QuarkusTransaction.joiningExisting().call(() -> { ...; return 42; });
      Returns:
      An interface that allow various options of a transaction runner to be customized, or a Runnable/Callable to be executed.
      See Also:

    • requiringNew

      static TransactionRunnerOptions requiringNew()
      Starts the definition of a transaction runner, which can then be used to run a task (Runnable, Callable, ...), with TransactionSemantics.REQUIRE_NEW semantics:
      • If an existing transaction is already associated with the current thread then the transaction is suspended, then a new transaction is started which follows all the normal lifecycle rules, and when it's complete the original transaction is resumed.
      • Otherwise a new transaction is started, and follows all the normal lifecycle rules.

      Examples of use: 

      
 QuarkusTransaction.requiringNew().run(() -> ...);
 int value = QuarkusTransaction.requiringNew().call(() -> { ...; return 42; });
      Returns:
      An interface that allow various options of a transaction runner to be customized, or a Runnable/Callable to be executed.
      See Also:

    • disallowingExisting

      static TransactionRunnerOptions disallowingExisting()
      Starts the definition of a transaction runner, which can then be used to run a task (Runnable, Callable, ...), with TransactionSemantics.DISALLOW_EXISTING semantics:
      • If a transaction is already associated with the current thread a QuarkusTransactionException will be thrown,
      • Otherwise a new transaction is started, and follows all the normal lifecycle rules.

      Examples of use: 

      
 QuarkusTransaction.requiringNew().run(() -> ...);
 int value = QuarkusTransaction.requiringNew().call(() -> { ...; return 42; });
      Returns:
      An interface that allow various options of a transaction runner to be customized, or a Runnable/Callable to be executed.
      See Also:

    • suspendingExisting

      static TransactionRunnerOptions suspendingExisting()
      Starts the definition of a transaction runner, which can then be used to run a task (Runnable, Callable, ...), with TransactionSemantics.SUSPEND_EXISTING semantics:
      • If no transaction is active then these semantics are basically a no-op.
      • If a transaction is active then it is suspended, and resumed after the task is run.
      • The exception handler will never be consulted when these semantics are in use, specifying both an exception handler and these semantics are considered an error.
      • These semantics allows for code to easily be run outside the scope of a transaction.

      Examples of use: 

      
 QuarkusTransaction.requiringNew().run(() -> ...);
 int value = QuarkusTransaction.requiringNew().call(() -> { ...; return 42; });
      Returns:
      An interface that allow various options of a transaction runner to be customized, or a Runnable/Callable to be executed.
      See Also:

    • runner

      static TransactionRunnerOptions runner(TransactionSemantics semantics)
      Starts the definition of a transaction runner, which can then be used to run a task (Runnable, Callable, ...), following the selected TransactionSemantics.

      Examples of use: 

      
 QuarkusTransaction.runner(TransactionSemantics.REQUIRE_NEW).run(() -> ...);
 QuarkusTransaction.runner(TransactionSemantics.JOIN_EXISTING).run(() -> ...);
 QuarkusTransaction.runner(TransactionSemantics.SUSPEND_EXISTING).run(() -> ...);
 QuarkusTransaction.runner(TransactionSemantics.DISALLOW_EXISTING).run(() -> ...);
 int value = QuarkusTransaction.runner(TransactionSemantics.REQUIRE_NEW).call(() -> { ...; return 42; });
 int value = QuarkusTransaction.runner(TransactionSemantics.JOIN_EXISTING).call(() -> { ...; return 42; });
 int value = QuarkusTransaction.runner(TransactionSemantics.SUSPEND_EXISTING).call(() -> { ...; return 42; });
 int value = QuarkusTransaction.runner(TransactionSemantics.DISALLOW_EXISTING).call(() -> { ...; return 42; });
      Parameters:
      semantics - The selected TransactionSemantics.
      Returns:
      An interface that allow various options of a transaction runner to be customized, or a Runnable/Callable to be executed.
      See Also:

    • run

      @Deprecated static void run(Runnable task)
      Deprecated.
      For the same semantics, use QuarkusTransaction.requiringNew().run(task). joiningExisting(), disallowingExisting(), suspendingExisting() and runner(TransactionSemantics) can also be used for alternate semantics and options.
      Runs a task in a new transaction with the default timeout. This defaults to Transactional.TxType.REQUIRES_NEW semantics, however alternate semantics can be requested using run(RunOptions, Runnable).
      Parameters:
      task - The task to run in a transaction

    • run

      @Deprecated static void run(RunOptions options, Runnable task)
      Deprecated.
      Use requiringNew(), joiningExisting(), disallowingExisting(), suspendingExisting() or runner(TransactionSemantics) instead.
      Runs a task in a new transaction with the default timeout. This defaults to Transactional.TxType.REQUIRES_NEW semantics, however alternate semantics can be specified using the options parameter.
      Parameters:
      options - Options that apply to the new transaction
      task - The task to run in a transaction

    • call

      @Deprecated static <T> T call(Callable<T> task)
      Deprecated.
      For the same semantics, use QuarkusTransaction.requiringNew().call(task). joiningExisting(), disallowingExisting(), suspendingExisting() and runner(TransactionSemantics) can also be used for alternate semantics and options.
      Calls a task in a new transaction with the default timeout. This defaults to Transactional.TxType.REQUIRES_NEW semantics, however alternate semantics can be requested using call(RunOptions, Callable).

      If the task throws a checked exception it will be wrapped with a QuarkusTransactionException

      Parameters:
      task - The task to run in a transaction

    • call

      @Deprecated static <T> T call(RunOptions options, Callable<T> task)
      Deprecated.
      Use requiringNew(), joiningExisting(), disallowingExisting(), suspendingExisting() or runner(TransactionSemantics) instead.
      Calls a task in a new transaction with the default timeout. This defaults to Transactional.TxType.REQUIRES_NEW semantics, however alternate semantics can be requested using the options parameter.

      If the task throws a checked exception it will be wrapped with a QuarkusTransactionException

      Parameters:
      options - Options that apply to the new transaction
      task - The task to run in a transaction

    • runOptions

      @Deprecated static RunOptions runOptions()
      Deprecated.
      Use requiringNew(), joiningExisting(), disallowingExisting(), suspendingExisting() or runner(TransactionSemantics) instead.
      Returns:
      a new RunOptions

    • beginOptions

      static BeginOptions beginOptions()
      Returns:
      a new BeginOptions