0
# Quarkus Narayana JTA Extension
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: quarkus-narayana-jta
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**: Add to your `pom.xml`:
10

11
```xml
12
<dependency>
13
    <groupId>io.quarkus</groupId>
14
    <artifactId>quarkus-narayana-jta</artifactId>
15
</dependency>
16
```
17

18
## Core Imports
19

20
Standard JTA interfaces are automatically available:
21

22
```java
23
import jakarta.transaction.Transactional;
24
import jakarta.transaction.UserTransaction;
25
import jakarta.transaction.TransactionManager;
26
```
27

28
Quarkus-specific enhanced API:
29

30
```java
31
import io.quarkus.narayana.jta.QuarkusTransaction;
32
import io.quarkus.narayana.jta.TransactionSemantics;
33
import io.quarkus.narayana.jta.TransactionRunnerOptions;
34
import io.quarkus.narayana.jta.runtime.TransactionConfiguration;
35
```
36

37
## Basic Usage
38

39
### Declarative Approach (Recommended)
40

41
```java
42
import jakarta.transaction.Transactional;
43
import io.quarkus.narayana.jta.runtime.TransactionConfiguration;
44

45
@ApplicationScoped
46
public class BookService {
47
    
48
    @Transactional
49
    public void createBook(Book book) {
50
        // Automatic transaction management
51
        entityManager.persist(book);
52
    }
53
    
54
    @Transactional(REQUIRES_NEW)
55
    @TransactionConfiguration(timeout = 30)
56
    public void auditOperation(String operation) {
57
        // New transaction with custom timeout
58
        auditRepository.log(operation);
59
    }
60
}
61
```
62

63
### Programmatic Approach
64

65
```java
66
import io.quarkus.narayana.jta.QuarkusTransaction;
67

68
@ApplicationScoped 
69
public class OrderService {
70
    
71
    public void processOrder(Order order) {
72
        // Lambda-style transaction with automatic rollback on exceptions
73
        QuarkusTransaction.requiringNew()
74
            .timeout(10)
75
            .run(() -> {
76
                validateOrder(order);
77
                chargePayment(order);
78
                updateInventory(order);
79
            });
80
    }
81
    
82
    public boolean attemptPayment(Payment payment) {
83
        // Manual transaction control
84
        QuarkusTransaction.begin();
85
        try {
86
            processPayment(payment);
87
            QuarkusTransaction.commit();
88
            return true;
89
        } catch (PaymentFailedException e) {
90
            QuarkusTransaction.rollback();
91
            return false;
92
        }
93
    }
94
}
95
```
96

97
## Architecture
98

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

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

108
## Capabilities
109

110
### Programmatic Transaction Management
111

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

114
```java { .api }
115
interface QuarkusTransaction {
116
    // Basic transaction control
117
    static void begin();
118
    static void begin(BeginOptions options);
119
    static void commit();
120
    static void rollback();
121
    static void setRollbackOnly();
122
    static int getStatus();
123
    static boolean isRollbackOnly();
124
    
125
    // Transaction runner factory methods
126
    static TransactionRunnerOptions requiringNew();
127
    static TransactionRunnerOptions joiningExisting();
128
    static TransactionRunnerOptions disallowingExisting();
129
    static TransactionRunnerOptions suspendingExisting();
130
    static TransactionRunnerOptions runner(TransactionSemantics semantics);
131
    
132
    // Builder factory
133
    static BeginOptions beginOptions();
134
}
135
```
136

137
[Programmatic Transaction Management](./programmatic-transactions.md)
138

139
### Declarative Transaction Management
140

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

143
```java { .api }
144
@Target({TYPE, METHOD})
145
@Retention(RUNTIME)
146
@interface Transactional {
147
    TxType value() default TxType.REQUIRED;
148
    Class[] rollbackOn() default {};
149
    Class[] dontRollbackOn() default {};
150
}
151

152
@Target({TYPE, METHOD})
153
@Retention(RUNTIME)
154
@interface TransactionConfiguration {
155
    int timeout() default -1;
156
    String timeoutFromConfigProperty() default "<<unset>>";
157
}
158
```
159

160
[Declarative Transaction Management](./declarative-transactions.md)
161

162
### Transaction Configuration
163

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

166
```java { .api }
167
interface TransactionManagerConfiguration {
168
    String nodeName();
169
    boolean shortenNodeNameIfNecessary();
170
    Duration defaultTransactionTimeout();
171
    boolean enableRecovery();
172
    ObjectStoreConfig objectStore();
173
}
174

175
enum ObjectStoreType {
176
    File_System, JDBC
177
}
178
```
179

180
[Transaction Configuration](./configuration.md)
181

182
### Transaction Semantics and Execution
183

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

186
```java { .api }
187
enum TransactionSemantics {
188
    DISALLOW_EXISTING,
189
    JOIN_EXISTING, 
190
    REQUIRE_NEW,
191
    SUSPEND_EXISTING
192
}
193

194
interface TransactionRunnerOptions extends TransactionRunner {
195
    TransactionRunnerOptions timeout(int seconds);
196
    TransactionRunnerOptions exceptionHandler(Function<Throwable, TransactionExceptionResult> handler);
197
    void run(Runnable task);
198
    <T> T call(Callable<T> task);
199
}
200
```
201

202
[Transaction Semantics and Execution](./transaction-semantics.md)
203

204
## Types
205

206
### Core Transaction Types
207

208
```java { .api }
209
class QuarkusTransactionException extends RuntimeException {
210
    public QuarkusTransactionException(Throwable cause);
211
    public QuarkusTransactionException(String message);
212
    public QuarkusTransactionException(String message, Throwable cause);
213
}
214

215
enum TransactionExceptionResult {
216
    COMMIT, ROLLBACK
217
}
218

219
class BeginOptions {
220
    public BeginOptions commitOnRequestScopeEnd();
221
    public BeginOptions timeout(int seconds);
222
}
223
```