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 Detail

      • 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:
        TransactionRunnerOptions

      • 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:
        TransactionRunnerOptions

      • 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:
        TransactionRunnerOptions

      • 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:
        TransactionRunnerOptions

      • 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:
        TransactionRunnerOptions

      • beginOptions

        static BeginOptions beginOptions()
        Returns:
        a new BeginOptions