0
# Exception Handling
1

2
Apache ActiveMQ Artemis Commons provides a comprehensive exception hierarchy with over 40 specific exception types, enabling precise error handling and diagnosis in message broker operations.
3

4
## Base Exception Classes
5

6
### ActiveMQException
7

8
The root exception class for all ActiveMQ Artemis API exceptions.
9

10
```java { .api }
11
class ActiveMQException extends Exception {
12
    // Constructors
13
    ActiveMQException();
14
    ActiveMQException(String message);
15
    ActiveMQException(ActiveMQExceptionType type);
16
    ActiveMQException(ActiveMQExceptionType type, String message);
17
    ActiveMQException(String message, Throwable cause);
18
    ActiveMQException(ActiveMQExceptionType type, String message, Throwable cause);
19
    
20
    // Exception type access
21
    ActiveMQExceptionType getType();
22
}
23
```
24

25
### Exception Type Enumeration
26

27
```java { .api }
28
enum ActiveMQExceptionType {
29
    // Exception type constants for categorizing different error conditions
30
    // (Specific values depend on implementation)
31
}
32
```
33

34
## Specific Exception Types
35

36
### Address and Queue Exceptions
37

38
```java { .api }
39
// Address does not exist
40
class ActiveMQAddressDoesNotExistException extends ActiveMQException {
41
    // Thrown when trying to access a non-existent address
42
}
43

44
// Address already exists
45
class ActiveMQAddressExistsException extends ActiveMQException {
46
    // Thrown when trying to create an address that already exists
47
}
48

49
// Address storage is full
50
class ActiveMQAddressFullException extends ActiveMQException {
51
    // Thrown when address cannot accept more messages due to storage limits
52
}
53

54
// Address deletion failed
55
class ActiveMQDeleteAddressException extends ActiveMQException {
56
    // Thrown when address deletion operation fails
57
}
58

59
// Queue does not exist
60
class ActiveMQNonExistentQueueException extends ActiveMQException {
61
    // Thrown when trying to access a non-existent queue
62
}
63

64
// Queue already exists
65
class ActiveMQQueueExistsException extends ActiveMQException {
66
    // Thrown when trying to create a queue that already exists
67
}
68

69
// Queue consumer limit reached
70
class ActiveMQQueueMaxConsumerLimitReached extends ActiveMQException {
71
    // Thrown when queue cannot accept more consumers
72
}
73

74
// Invalid queue configuration
75
class ActiveMQInvalidQueueConfiguration extends ActiveMQException {
76
    // Thrown when queue configuration is invalid
77
}
78

79
// Invalid transient queue usage
80
class ActiveMQInvalidTransientQueueUseException extends ActiveMQException {
81
    // Thrown when transient queue is used incorrectly
82
}
83
```
84

85
### Connection and Session Exceptions
86

87
```java { .api }
88
// Connection timed out
89
class ActiveMQConnectionTimedOutException extends ActiveMQException {
90
    // Thrown when connection establishment times out
91
}
92

93
// Client disconnected
94
class ActiveMQDisconnectedException extends ActiveMQException {
95
    // Thrown when client is unexpectedly disconnected
96
}
97

98
// Remote disconnect
99
class ActiveMQRemoteDisconnectException extends ActiveMQException {
100
    // Thrown when remote party initiates disconnection
101
}
102

103
// Not connected
104
class ActiveMQNotConnectedException extends ActiveMQException {
105
    // Thrown when operation requires connection but client is not connected
106
}
107

108
// Session creation failed
109
class ActiveMQSessionCreationException extends ActiveMQException {
110
    // Thrown when session cannot be created
111
}
112

113
// Incompatible client-server versions
114
class ActiveMQIncompatibleClientServerException extends ActiveMQException {
115
    // Thrown when client and server versions are incompatible
116
}
117
```
118

119
### Transaction Exceptions
120

121
```java { .api }
122
// Transaction outcome unknown
123
class ActiveMQTransactionOutcomeUnknownException extends ActiveMQException {
124
    // Thrown when transaction outcome cannot be determined
125
}
126

127
// Transaction rolled back
128
class ActiveMQTransactionRolledBackException extends ActiveMQException {
129
    // Thrown when transaction is rolled back
130
}
131

132
// Transaction timeout
133
class ActiveMQTransactionTimeoutException extends ActiveMQException {
134
    // Thrown when transaction exceeds timeout limit
135
}
136
```
137

138
### Security Exceptions
139

140
```java { .api }
141
// Security violation
142
class ActiveMQSecurityException extends ActiveMQException {
143
    // Thrown when security constraints are violated
144
}
145

146
// Cluster security violation
147
class ActiveMQClusterSecurityException extends ActiveMQException {
148
    // Thrown when cluster security is violated
149
}
150
```
151

152
### I/O and System Exceptions
153

154
```java { .api }
155
// I/O error
156
class ActiveMQIOErrorException extends ActiveMQException {
157
    // Thrown when I/O operations fail
158
}
159

160
// Native I/O error
161
class ActiveMQNativeIOError extends ActiveMQException {
162
    // Thrown when native I/O operations fail
163
}
164

165
// Internal error
166
class ActiveMQInternalErrorException extends ActiveMQException {
167
    // Thrown when internal system errors occur
168
}
169

170
// System shutdown
171
class ActiveMQShutdownException extends ActiveMQException {
172
    // Thrown when system is shutting down
173
}
174

175
// Object closed
176
class ActiveMQObjectClosedException extends ActiveMQException {
177
    // Thrown when trying to use a closed object
178
}
179
```
180

181
### Message and Buffer Exceptions
182

183
```java { .api }
184
// Large message error
185
class ActiveMQLargeMessageException extends ActiveMQException {
186
    // Thrown when large message processing fails
187
}
188

189
// Large message interrupted
190
class ActiveMQLargeMessageInterruptedException extends ActiveMQException {
191
    // Thrown when large message processing is interrupted
192
}
193

194
// Invalid buffer
195
class ActiveMQInvalidBufferException extends ActiveMQException {
196
    // Thrown when buffer is invalid or corrupted
197
}
198

199

200
// Unsupported packet
201
class ActiveMQUnsupportedPacketException extends ActiveMQException {
202
    // Thrown when packet type is not supported
203
}
204

205
// Interceptor rejected packet
206
class ActiveMQInterceptorRejectedPacketException extends ActiveMQException {
207
    // Thrown when message interceptor rejects packet
208
}
209
```
210

211
### Routing and Filter Exceptions
212

213
```java { .api }
214
// Routing error
215
class ActiveMQRoutingException extends ActiveMQException {
216
    // Thrown when message routing fails
217
}
218

219
// Unexpected routing type
220
class ActiveMQUnexpectedRoutingTypeForAddress extends ActiveMQException {
221
    // Thrown when routing type doesn't match address configuration
222
}
223

224
// Invalid filter expression
225
class ActiveMQInvalidFilterExpressionException extends ActiveMQException {
226
    // Thrown when message filter expression is invalid
227
}
228

229
// Divert does not exist
230
class ActiveMQDivertDoesNotExistException extends ActiveMQException {
231
    // Thrown when trying to access non-existent divert
232
}
233
```
234

235
### Data and State Exceptions
236

237
```java { .api }
238
// Duplicate ID violation
239
class ActiveMQDuplicateIdException extends ActiveMQException {
240
    // Thrown when duplicate ID is detected
241
}
242

243
// Duplicate metadata
244
class ActiveMQDuplicateMetaDataException extends ActiveMQException {
245
    // Thrown when duplicate metadata is encountered
246
}
247

248
// Illegal state
249
class ActiveMQIllegalStateException extends ActiveMQException {
250
    // Thrown when object is in illegal state for operation
251
}
252

253
// Null reference
254
class ActiveMQNullRefException extends ActiveMQException {
255
    // Thrown when null reference is encountered unexpectedly
256
}
257

258
// Property conversion error
259
class ActiveMQPropertyConversionException extends ActiveMQException {
260
    // Thrown when property type conversion fails
261
}
262
```
263

264
### Threading and Interruption Exceptions
265

266
```java { .api }
267
// Thread interruption
268
class ActiveMQInterruptedException extends ActiveMQException {
269
    // Thrown when thread is interrupted during operation
270
}
271

272
// Unblocked operation
273
class ActiveMQUnBlockedException extends ActiveMQException {
274
    // Thrown when blocking operation is unblocked
275
}
276
```
277

278
### Replication and Timeout Exceptions
279

280
```java { .api }
281
// Already replicating
282
class ActiveMQAlreadyReplicatingException extends ActiveMQException {
283
    // Thrown when replication is already in progress
284
}
285

286
// Replication timeout
287
class ActiveMQReplicationTimeooutException extends ActiveMQException {
288
    // Thrown when replication operation times out
289
}
290

291
// Operation timeout
292
class ActiveMQTimeoutException extends ActiveMQException {
293
    // Thrown when operation exceeds timeout limit
294
}
295
```
296

297
## Exception Handling Patterns
298

299
### Basic Exception Handling
300

301
```java
302
import org.apache.activemq.artemis.api.core.ActiveMQException;
303
import org.apache.activemq.artemis.api.core.ActiveMQExceptionType;
304

305
try {
306
    // ActiveMQ operations
307
    performArtemisOperation();
308
} catch (ActiveMQException e) {
309
    ActiveMQExceptionType type = e.getType();
310
    
311
    // Handle based on exception type
312
    switch (type) {
313
        case /* specific type */:
314
            // Handle specific error condition
315
            break;
316
        default:
317
            // Generic error handling
318
            logger.error("ActiveMQ operation failed", e);
319
    }
320
}
321
```
322

323
### Specific Exception Handling
324

325
```java
326
import org.apache.activemq.artemis.api.core.ActiveMQAddressFullException;
327
import org.apache.activemq.artemis.api.core.ActiveMQConnectionTimedOutException;
328
import org.apache.activemq.artemis.api.core.ActiveMQSecurityException;
329

330
try {
331
    // Queue or connection operations
332
    createQueueAndConnect();
333
} catch (ActiveMQAddressFullException e) {
334
    // Handle address full - maybe retry later or use different address
335
    handleAddressFull(e);
336
} catch (ActiveMQConnectionTimedOutException e) {
337
    // Handle connection timeout - retry with different parameters
338
    retryConnection(e);
339
} catch (ActiveMQSecurityException e) {
340
    // Handle security violation - check credentials or permissions
341
    handleSecurityError(e);
342
} catch (ActiveMQException e) {
343
    // Handle other ActiveMQ exceptions
344
    handleGenericActiveMQError(e);
345
}
346
```
347

348
### Transaction Exception Handling
349

350
```java
351
import org.apache.activemq.artemis.api.core.ActiveMQTransactionRolledBackException;
352
import org.apache.activemq.artemis.api.core.ActiveMQTransactionTimeoutException;
353

354
try {
355
    // Transaction operations
356
    performTransactionalWork();
357
    commitTransaction();
358
} catch (ActiveMQTransactionRolledBackException e) {
359
    // Transaction was rolled back - handle cleanup
360
    handleRollback(e);
361
} catch (ActiveMQTransactionTimeoutException e) {
362
    // Transaction timed out - may need to retry or extend timeout
363
    handleTransactionTimeout(e);
364
}
365
```
366

367
### Resource Management with Exceptions
368

369
```java
370
import org.apache.activemq.artemis.api.core.ActiveMQObjectClosedException;
371

372
try {
373
    // Use ActiveMQ resources
374
    useActiveMQResource(resource);
375
} catch (ActiveMQObjectClosedException e) {
376
    // Resource was closed - recreate or use alternative
377
    recreateResource();
378
} finally {
379
    // Always clean up resources
380
    if (resource != null) {
381
        try {
382
            resource.close();
383
        } catch (ActiveMQException e) {
384
            logger.warn("Error closing resource", e);
385
        }
386
    }
387
}
388
```
389

390
## Exception Categories
391

392
### Runtime vs Checked Exceptions
393

394
All ActiveMQ exceptions extend `Exception` (checked exception), requiring explicit handling or declaration in method signatures.
395

396
### Recoverable vs Non-Recoverable
397

398
- **Recoverable**: `ActiveMQConnectionTimedOutException`, `ActiveMQAddressFullException` - operations can be retried
399
- **Non-Recoverable**: `ActiveMQSecurityException`, `ActiveMQInternalErrorException` - require configuration or system changes
400

401
### Transient vs Persistent
402

403
- **Transient**: `ActiveMQTimeoutException`, `ActiveMQInterruptedException` - may succeed on retry
404
- **Persistent**: `ActiveMQAddressDoesNotExistException`, `ActiveMQInvalidFilterExpressionException` - require corrective action