tessl/maven-io-quarkus--quarkus-narayana-jta

JTA transaction support for Quarkus applications with programmatic and declarative transaction management

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Quarkus Narayana JTA Extension

Name: tessl/maven-io-quarkus--quarkus-narayana-jta
Author: tessl

Quarkus Narayana JTA Extension provides comprehensive JTA (Jakarta Transactions API) transaction support for Java applications running on the Quarkus framework. It integrates the Narayana transaction manager to enable both declarative (@Transactional) and programmatic transaction management with cloud-native optimizations.

Package Information

Package Name: quarkus-narayana-jta
Package Type: Maven
Language: Java
Installation: Add to your pom.xml:

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-narayana-jta</artifactId>
</dependency>

Core Imports

Standard JTA interfaces are automatically available:

import jakarta.transaction.Transactional;
import jakarta.transaction.UserTransaction;
import jakarta.transaction.TransactionManager;

Quarkus-specific enhanced API:

import io.quarkus.narayana.jta.QuarkusTransaction;
import io.quarkus.narayana.jta.TransactionSemantics;
import io.quarkus.narayana.jta.TransactionRunnerOptions;
import io.quarkus.narayana.jta.runtime.TransactionConfiguration;

Basic Usage

Declarative Approach (Recommended)

import jakarta.transaction.Transactional;
import io.quarkus.narayana.jta.runtime.TransactionConfiguration;

@ApplicationScoped
public class BookService {
    
    @Transactional
    public void createBook(Book book) {
        // Automatic transaction management
        entityManager.persist(book);
    }
    
    @Transactional(REQUIRES_NEW)
    @TransactionConfiguration(timeout = 30)
    public void auditOperation(String operation) {
        // New transaction with custom timeout
        auditRepository.log(operation);
    }
}

Programmatic Approach

import io.quarkus.narayana.jta.QuarkusTransaction;

@ApplicationScoped 
public class OrderService {
    
    public void processOrder(Order order) {
        // Lambda-style transaction with automatic rollback on exceptions
        QuarkusTransaction.requiringNew()
            .timeout(10)
            .run(() -> {
                validateOrder(order);
                chargePayment(order);
                updateInventory(order);
            });
    }
    
    public boolean attemptPayment(Payment payment) {
        // Manual transaction control
        QuarkusTransaction.begin();
        try {
            processPayment(payment);
            QuarkusTransaction.commit();
            return true;
        } catch (PaymentFailedException e) {
            QuarkusTransaction.rollback();
            return false;
        }
    }
}

Architecture

The Quarkus Narayana JTA Extension is built around several key components:

QuarkusTransaction Interface: Simplified programmatic API with no checked exceptions and automatic leak prevention
Transaction Semantics: Four different transaction propagation behaviors (REQUIRE_NEW, JOIN_EXISTING, DISALLOW_EXISTING, SUSPEND_EXISTING)
Request Scope Integration: Transactions are tied to request scope to prevent leaks
Configuration System: Comprehensive runtime and build-time configuration options
CDI Integration: Transaction-scoped beans and lifecycle events
Recovery Support: Optional transaction recovery for production reliability

Capabilities

Programmatic Transaction Management

Core programmatic API providing simplified transaction control with lambda-style execution and comprehensive semantic options.

interface QuarkusTransaction {
    // Basic transaction control
    static void begin();
    static void begin(BeginOptions options);
    static void commit();
    static void rollback();
    static void setRollbackOnly();
    static int getStatus();
    static boolean isRollbackOnly();
    
    // Transaction runner factory methods
    static TransactionRunnerOptions requiringNew();
    static TransactionRunnerOptions joiningExisting();
    static TransactionRunnerOptions disallowingExisting();
    static TransactionRunnerOptions suspendingExisting();
    static TransactionRunnerOptions runner(TransactionSemantics semantics);
    
    // Builder factory
    static BeginOptions beginOptions();
}

Programmatic Transaction Management

Declarative Transaction Management

Standard JTA @Transactional annotations with Quarkus-specific enhancements for timeout configuration and lifecycle management.

@Target({TYPE, METHOD})
@Retention(RUNTIME)
@interface Transactional {
    TxType value() default TxType.REQUIRED;
    Class[] rollbackOn() default {};
    Class[] dontRollbackOn() default {};
}

@Target({TYPE, METHOD})
@Retention(RUNTIME)
@interface TransactionConfiguration {
    int timeout() default -1;
    String timeoutFromConfigProperty() default "<<unset>>";
}

Declarative Transaction Management

Transaction Configuration

Comprehensive configuration system supporting node identification, timeouts, object store types, and recovery options.

interface TransactionManagerConfiguration {
    String nodeName();
    boolean shortenNodeNameIfNecessary();
    Duration defaultTransactionTimeout();
    boolean enableRecovery();
    ObjectStoreConfig objectStore();
}

enum ObjectStoreType {
    File_System, JDBC
}

Transaction Configuration

Transaction Semantics and Execution

Advanced transaction execution with customizable propagation behaviors, exception handling, and timeout control.

enum TransactionSemantics {
    DISALLOW_EXISTING,
    JOIN_EXISTING, 
    REQUIRE_NEW,
    SUSPEND_EXISTING
}

interface TransactionRunnerOptions extends TransactionRunner {
    TransactionRunnerOptions timeout(int seconds);
    TransactionRunnerOptions exceptionHandler(Function<Throwable, TransactionExceptionResult> handler);
    void run(Runnable task);
    <T> T call(Callable<T> task);
}

Transaction Semantics and Execution

Types

Core Transaction Types

class QuarkusTransactionException extends RuntimeException {
    public QuarkusTransactionException(Throwable cause);
    public QuarkusTransactionException(String message);
    public QuarkusTransactionException(String message, Throwable cause);
}

enum TransactionExceptionResult {
    COMMIT, ROLLBACK
}

class BeginOptions {
    public BeginOptions commitOnRequestScopeEnd();
    public BeginOptions timeout(int seconds);
}