0
# Bulkhead Strategies
1
2
Isolation patterns that control concurrent access to methods by limiting simultaneous executions and managing queuing for asynchronous operations.
3
4
## Capabilities
5
6
### Basic Bulkhead
7
8
Standard bulkhead functionality with configurable concurrency limits and queue management.
9
10
```java { .api }
11
@Bulkhead(
12
value = 10,
13
waitingTaskQueue = 20
14
)
15
public ReturnType limitedConcurrencyMethod();
16
```
17
18
#### Parameters
19
20
- `value` - Maximum concurrent executions (default: 10)
21
- `waitingTaskQueue` - Queue size for asynchronous operations (default: 10)
22
23
#### Behavior
24
25
- **Synchronous methods**: Rejected immediately when limit exceeded
26
- **Asynchronous methods**: Queued when concurrent limit reached, rejected when queue full
27
28
#### Usage Example
29
30
```java
31
@ApplicationScoped
32
public class DatabaseService {
33
34
// Limit database connections
35
@Bulkhead(value = 5, waitingTaskQueue = 15)
36
public List<User> findUsers(UserQuery query) throws SQLException {
37
return userRepository.query(query);
38
}
39
40
// Protect critical resource with tight limit
41
@Bulkhead(value = 2)
42
public void performMaintenanceTask() throws MaintenanceException {
43
criticalSystemMaintenance.execute();
44
}
45
46
// Async operations with queue management
47
@Asynchronous
48
@Bulkhead(value = 8, waitingTaskQueue = 25)
49
public CompletionStage<ProcessingResult> processAsync(ProcessingTask task) {
50
return CompletableFuture.supplyAsync(() -> processor.process(task));
51
}
52
}
53
```
54
55
### Bulkhead with Other Strategies
56
57
Combining bulkhead isolation with other fault tolerance patterns.
58
59
```java { .api }
60
@Bulkhead(value = 5, waitingTaskQueue = 10)
61
@CircuitBreaker(requestVolumeThreshold = 20, failureRatio = 0.4)
62
@Timeout(8000)
63
public ReturnType isolatedResilientMethod();
64
```
65
66
#### Usage Example
67
68
```java
69
@ApplicationScoped
70
public class ExternalApiService {
71
72
// API calls with bulkhead, circuit breaker, and retry
73
@Bulkhead(value = 6, waitingTaskQueue = 12)
74
@CircuitBreaker(requestVolumeThreshold = 15, failureRatio = 0.5)
75
@Retry(maxRetries = 2, delay = 1000)
76
@Timeout(10000)
77
public ApiResponse callExternalApi(ApiRequest request) throws ApiException {
78
return externalApiClient.call(request);
79
}
80
81
// Payment processing with isolation and fallback
82
@Bulkhead(value = 3)
83
@Fallback(fallbackMethod = "queuePayment")
84
@Timeout(15000)
85
public PaymentResult processPayment(PaymentRequest request) throws PaymentException {
86
return paymentGateway.process(request);
87
}
88
89
public PaymentResult queuePayment(PaymentRequest request) {
90
paymentQueue.enqueue(request);
91
return PaymentResult.queued(request.getId());
92
}
93
}
94
```
95
96
### Resource-specific Bulkheads
97
98
Different bulkhead configurations for different resource types or operations.
99
100
#### Usage Example
101
102
```java
103
@ApplicationScoped
104
public class ResourceManager {
105
106
// File system operations - limited by I/O capacity
107
@Bulkhead(value = 4, waitingTaskQueue = 8)
108
public FileProcessingResult processFile(File file) throws IOException {
109
return fileProcessor.process(file);
110
}
111
112
// Network operations - higher concurrency allowed
113
@Bulkhead(value = 15, waitingTaskQueue = 30)
114
public NetworkResponse sendNetworkRequest(NetworkRequest request) {
115
return networkClient.send(request);
116
}
117
118
// CPU-intensive operations - match CPU cores
119
@Bulkhead(value = Runtime.getRuntime().availableProcessors())
120
public ComputationResult performComputation(ComputationTask task) {
121
return computationEngine.compute(task);
122
}
123
124
// Memory-sensitive operations - very limited
125
@Bulkhead(value = 2, waitingTaskQueue = 3)
126
public ProcessingResult processLargeDataSet(LargeDataSet dataSet) {
127
return memoryIntensiveProcessor.process(dataSet);
128
}
129
}
130
```
131
132
### Async Bulkhead Patterns
133
134
Specialized patterns for asynchronous and reactive programming.
135
136
```java { .api }
137
@Asynchronous
138
@Bulkhead(value = 10, waitingTaskQueue = 20)
139
public CompletionStage<ReturnType> asyncBulkheadMethod();
140
141
@AsynchronousNonBlocking
142
@Bulkhead(value = 8, waitingTaskQueue = 15)
143
public Uni<ReturnType> nonBlockingBulkheadMethod();
144
```
145
146
#### Usage Example
147
148
```java
149
@ApplicationScoped
150
public class AsyncProcessingService {
151
152
// Async image processing with bulkhead
153
@Asynchronous
154
@Bulkhead(value = 6, waitingTaskQueue = 20)
155
@Timeout(30000)
156
public CompletionStage<ProcessedImage> processImageAsync(ImageData image) {
157
return CompletableFuture.supplyAsync(() -> {
158
return imageProcessor.process(image);
159
});
160
}
161
162
// Non-blocking email sending with bulkhead
163
@AsynchronousNonBlocking
164
@Bulkhead(value = 12, waitingTaskQueue = 25)
165
@Retry(maxRetries = 3)
166
public Uni<EmailResult> sendEmailAsync(EmailMessage message) {
167
return emailService.sendAsync(message);
168
}
169
170
// Batch processing with controlled concurrency
171
@Asynchronous
172
@Bulkhead(value = 4, waitingTaskQueue = 10)
173
public CompletionStage<BatchResult> processBatchAsync(List<BatchItem> items) {
174
return CompletableFuture.supplyAsync(() -> {
175
return batchProcessor.process(items);
176
});
177
}
178
}
179
```
180
181
## Types
182
183
### Bulkhead Core Types
184
185
```java { .api }
186
// Bulkhead rejection exception
187
class BulkheadException extends RuntimeException {
188
public BulkheadException(String message);
189
public BulkheadException(String message, Throwable cause);
190
}
191
192
// Async execution types
193
interface CompletionStage<T> {
194
// Java standard CompletionStage methods
195
}
196
197
// Mutiny reactive type
198
interface Uni<T> {
199
// Mutiny Uni methods for non-blocking operations
200
}
201
```