0
# Exceptions
1

2
Comprehensive exception handling for various error scenarios in stream processing operations. Siddhi Core provides a hierarchy of exceptions to handle different types of errors that can occur during application creation, runtime execution, and state management.
3

4
## Core Exceptions
5

6
### SiddhiException Hierarchy
7

8
Base exception class for all Siddhi-related exceptions providing common exception handling patterns.
9

10
```java { .api }
11
public class SiddhiException extends RuntimeException {
12
    public SiddhiException(String message);
13
    public SiddhiException(String message, Throwable cause);
14
    public SiddhiException(Throwable cause);
15
}
16
```
17

18
## Application Lifecycle Exceptions
19

20
### SiddhiAppCreationException
21

22
Thrown during Siddhi app creation errors when parsing or validating Siddhi applications.
23

24
```java { .api }
25
public class SiddhiAppCreationException extends SiddhiException {
26
    public SiddhiAppCreationException(String message);
27
    public SiddhiAppCreationException(String message, Throwable cause);
28
    public SiddhiAppCreationException(Throwable cause);
29
}
30
```
31

32
### SiddhiAppRuntimeException
33

34
Runtime errors in Siddhi app execution occurring during event processing or query execution.
35

36
```java { .api }
37
public class SiddhiAppRuntimeException extends SiddhiException {
38
    public SiddhiAppRuntimeException(String message);
39
    public SiddhiAppRuntimeException(String message, Throwable cause);
40
    public SiddhiAppRuntimeException(Throwable cause);
41
}
42
```
43

44
### Usage Examples
45

46
```java
47
// Handle application creation errors
48
try {
49
    SiddhiAppRuntime runtime = siddhiManager.createSiddhiAppRuntime(invalidSiddhiApp);
50
} catch (SiddhiAppCreationException e) {
51
    System.err.println("Failed to create Siddhi app: " + e.getMessage());
52
    
53
    // Log detailed error information
54
    if (e.getCause() instanceof ParseException) {
55
        System.err.println("Syntax error in Siddhi query");
56
    } else if (e.getCause() instanceof ValidationException) {
57
        System.err.println("Validation error in Siddhi app definition");
58
    }
59
    
60
    // Handle gracefully
61
    fallbackToDefaultApp();
62
}
63

64
// Handle runtime errors
65
try {
66
    InputHandler handler = runtime.getInputHandler("StockStream");
67
    handler.send(malformedData);
68
} catch (SiddhiAppRuntimeException e) {
69
    System.err.println("Runtime error during event processing: " + e.getMessage());
70
    
71
    // Implement error recovery
72
    handleRuntimeError(e, malformedData);
73
}
74
```
75

76
## Definition and Query Exceptions
77

78
### DefinitionNotExistException
79

80
Thrown when referenced definition doesn't exist in the Siddhi application.
81

82
```java { .api }
83
public class DefinitionNotExistException extends SiddhiException {
84
    public DefinitionNotExistException(String message);
85
    public DefinitionNotExistException(String message, Throwable cause);
86
}
87
```
88

89
### QueryNotExistException
90

91
Thrown when referenced query doesn't exist in the Siddhi application.
92

93
```java { .api }
94
public class QueryNotExistException extends SiddhiException {
95
    public QueryNotExistException(String message);
96
    public QueryNotExistException(String message, Throwable cause);
97
}
98
```
99

100
### Usage Examples
101

102
```java
103
// Handle missing definitions
104
try {
105
    InputHandler handler = runtime.getInputHandler("NonExistentStream");
106
} catch (DefinitionNotExistException e) {
107
    System.err.println("Stream not found: " + e.getMessage());
108
    
109
    // List available streams
110
    Map<String, StreamDefinition> streams = runtime.getStreamDefinitionMap();
111
    System.out.println("Available streams: " + streams.keySet());
112
    
113
    // Use fallback stream
114
    handler = runtime.getInputHandler("DefaultStream");
115
}
116

117
// Handle missing queries
118
try {
119
    runtime.addCallback("NonExistentQuery", queryCallback);
120
} catch (QueryNotExistException e) {
121
    System.err.println("Query not found: " + e.getMessage());
122
    
123
    // List available queries
124
    Set<String> queries = runtime.getQueryNames();
125
    System.out.println("Available queries: " + queries);
126
    
127
    // Register with existing query
128
    runtime.addCallback(queries.iterator().next(), queryCallback);
129
}
130
```
131

132
## Store Query Exceptions
133

134
### StoreQueryCreationException
135

136
Errors during store query creation when parsing or validating store queries.
137

138
```java { .api }
139
public class StoreQueryCreationException extends SiddhiException {
140
    public StoreQueryCreationException(String message);
141
    public StoreQueryCreationException(String message, Throwable cause);
142
}
143
```
144

145
### StoreQueryRuntimeException
146

147
Runtime errors in store query execution during on-demand query processing.
148

149
```java { .api }
150
public class StoreQueryRuntimeException extends SiddhiException {
151
    public StoreQueryRuntimeException(String message);
152
    public StoreQueryRuntimeException(String message, Throwable cause);
153
}
154
```
155

156
### Usage Examples
157

158
```java
159
// Handle store query creation errors
160
try {
161
    String invalidQuery = "from NonExistentTable select *";
162
    Event[] results = runtime.query(invalidQuery);
163
} catch (StoreQueryCreationException e) {
164
    System.err.println("Invalid store query: " + e.getMessage());
165
    
166
    // Validate query syntax
167
    if (e.getMessage().contains("table")) {
168
        System.err.println("Check table name and definition");
169
    }
170
    
171
    // Use corrected query
172
    String correctedQuery = "from StockTable select *";
173
    results = runtime.query(correctedQuery);
174
}
175

176
// Handle store query runtime errors
177
try {
178
    String query = "from StockTable on price > ? select *"; // Missing parameter
179
    Event[] results = runtime.query(query);
180
} catch (StoreQueryRuntimeException e) {
181
    System.err.println("Store query execution failed: " + e.getMessage());
182
    
183
    // Use parameterized query properly
184
    String paramQuery = "from StockTable on price > 100 select *";
185
    results = runtime.query(paramQuery);
186
}
187
```
188

189
## State Management Exceptions
190

191
### CannotRestoreSiddhiAppStateException
192

193
State restoration failures when attempting to restore Siddhi application state.
194

195
```java { .api }
196
public class CannotRestoreSiddhiAppStateException extends SiddhiException {
197
    public CannotRestoreSiddhiAppStateException(String message);
198
    public CannotRestoreSiddhiAppStateException(String message, Throwable cause);
199
}
200
```
201

202
### CannotClearSiddhiAppStateException
203

204
State clearing failures when attempting to clear stored state.
205

206
```java { .api }
207
public class CannotClearSiddhiAppStateException extends SiddhiException {
208
    public CannotClearSiddhiAppStateException(String message);
209
    public CannotClearSiddhiAppStateException(String message, Throwable cause);
210
}
211
```
212

213
### Usage Examples
214

215
```java
216
// Handle state restoration errors
217
try {
218
    runtime.restoreLastRevision();
219
} catch (CannotRestoreSiddhiAppStateException e) {
220
    System.err.println("Failed to restore state: " + e.getMessage());
221
    
222
    // Try alternative restoration methods
223
    try {
224
        byte[] snapshot = loadBackupSnapshot();
225
        runtime.restore(snapshot);
226
    } catch (Exception backupError) {
227
        System.err.println("Backup restoration also failed, starting fresh");
228
        // Start with clean state
229
    }
230
}
231

232
// Handle state clearing errors
233
try {
234
    runtime.clearAllRevisions();
235
} catch (CannotClearSiddhiAppStateException e) {
236
    System.err.println("Failed to clear state: " + e.getMessage());
237
    
238
    // Manual cleanup
239
    if (e.getCause() instanceof IOException) {
240
        System.err.println("File system issue, check permissions");
241
    } else if (e.getCause() instanceof SQLException) {
242
        System.err.println("Database issue, check connection");
243
    }
244
}
245
```
246

247
## Persistence Exceptions
248

249
### PersistenceStoreException
250

251
Persistence store related errors during state save/load operations.
252

253
```java { .api }
254
public class PersistenceStoreException extends SiddhiException {
255
    public PersistenceStoreException(String message);
256
    public PersistenceStoreException(String message, Throwable cause);
257
}
258
```
259

260
### NoPersistenceStoreException
261

262
Thrown when persistence store is not configured but persistence operations are attempted.
263

264
```java { .api }
265
public class NoPersistenceStoreException extends SiddhiException {
266
    public NoPersistenceStoreException(String message);
267
}
268
```
269

270
### Usage Examples
271

272
```java
273
// Handle persistence store errors
274
try {
275
    PersistenceReference ref = runtime.persist();
276
} catch (PersistenceStoreException e) {
277
    System.err.println("Persistence failed: " + e.getMessage());
278
    
279
    // Implement fallback persistence
280
    try {
281
        byte[] snapshot = runtime.snapshot();
282
        saveSnapshotToAlternateStore(snapshot);
283
    } catch (Exception fallbackError) {
284
        System.err.println("Fallback persistence also failed");
285
        // Log for manual recovery
286
        logStateForManualRecovery();
287
    }
288
}
289

290
// Handle missing persistence store
291
try {
292
    siddhiManager.persist();
293
} catch (NoPersistenceStoreException e) {
294
    System.err.println("No persistence store configured: " + e.getMessage());
295
    
296
    // Configure default persistence store
297
    FilePersistenceStore defaultStore = new FilePersistenceStore("./default-state");
298
    siddhiManager.setPersistenceStore(defaultStore);
299
    
300
    // Retry persistence
301
    siddhiManager.persist();
302
}
303
```
304

305
## Data Processing Exceptions
306

307
### DataPurgingException
308

309
Data purging operation errors during incremental data cleanup.
310

311
```java { .api }
312
public class DataPurgingException extends SiddhiException {
313
    public DataPurgingException(String message);
314
    public DataPurgingException(String message, Throwable cause);
315
}
316
```
317

318
### NoSuchAttributeException
319

320
Invalid attribute reference errors when accessing non-existent attributes.
321

322
```java { .api }
323
public class NoSuchAttributeException extends SiddhiException {
324
    public NoSuchAttributeException(String message);
325
    public NoSuchAttributeException(String message, Throwable cause);
326
}
327
```
328

329
### Usage Examples
330

331
```java
332
// Handle data purging errors
333
try {
334
    runtime.setPurgingEnabled(true);
335
    // Purging happens automatically
336
} catch (DataPurgingException e) {
337
    System.err.println("Data purging failed: " + e.getMessage());
338
    
339
    // Implement manual cleanup
340
    if (e.getCause() instanceof SQLException) {
341
        // Database purging failed
342
        executeDatabaseCleanup();
343
    } else {
344
        // File system purging failed
345
        executeFileSystemCleanup();
346
    }
347
}
348

349
// Handle attribute access errors
350
try {
351
    String query = "from StockTable select nonExistentColumn";
352
    Event[] results = runtime.query(query);
353
} catch (NoSuchAttributeException e) {
354
    System.err.println("Attribute not found: " + e.getMessage());
355
    
356
    // Get available attributes
357
    Attribute[] attributes = runtime.getStoreQueryOutputAttributes("from StockTable select *");
358
    System.out.println("Available attributes:");
359
    for (Attribute attr : attributes) {
360
        System.out.println("- " + attr.getName() + " (" + attr.getType() + ")");
361
    }
362
    
363
    // Use corrected query
364
    String correctedQuery = "from StockTable select symbol, price";
365
    results = runtime.query(correctedQuery);
366
}
367
```
368

369
## Connection and Operation Exceptions
370

371
### ConnectionUnavailableException
372

373
Connection unavailability errors when external systems are not accessible.
374

375
```java { .api }
376
public class ConnectionUnavailableException extends SiddhiException {
377
    public ConnectionUnavailableException(String message);
378
    public ConnectionUnavailableException(String message, Throwable cause);
379
}
380
```
381

382
### OperationNotSupportedException
383

384
Unsupported operations when attempting operations not available in current context.
385

386
```java { .api }
387
public class OperationNotSupportedException extends SiddhiException {
388
    public OperationNotSupportedException(String message);
389
    public OperationNotSupportedException(String message, Throwable cause);
390
}
391
```
392

393
### Usage Examples
394

395
```java
396
// Handle connection errors
397
try {
398
    // Sink attempting to connect to external system
399
    runtime.start(); // May fail if external connections are down
400
} catch (ConnectionUnavailableException e) {
401
    System.err.println("External system unavailable: " + e.getMessage());
402
    
403
    // Implement retry logic
404
    RetryPolicy retryPolicy = new RetryPolicy()
405
            .withMaxRetries(3)
406
            .withDelay(Duration.ofSeconds(5));
407
    
408
    retryPolicy.execute(() -> {
409
        runtime.start();
410
        return null;
411
    });
412
}
413

414
// Handle unsupported operations
415
try {
416
    // Some operations may not be supported in certain contexts
417
    runtime.someUnsupportedOperation();
418
} catch (OperationNotSupportedException e) {
419
    System.err.println("Operation not supported: " + e.getMessage());
420
    
421
    // Use alternative approach
422
    useAlternativeMethod();
423
}
424
```
425

426
## Extension and Configuration Exceptions
427

428
### CannotLoadClassException
429

430
Class loading failures when loading extension classes or dependencies.
431

432
```java { .api }
433
public class CannotLoadClassException extends SiddhiException {
434
    public CannotLoadClassException(String message);
435
    public CannotLoadClassException(String message, Throwable cause);
436
}
437
```
438

439
### CannotLoadConfigurationException
440

441
Configuration loading failures when reading configuration files or settings.
442

443
```java { .api }
444
public class CannotLoadConfigurationException extends SiddhiException {
445
    public CannotLoadConfigurationException(String message);
446
    public CannotLoadConfigurationException(String message, Throwable cause);
447
}
448
```
449

450
### QueryableRecordTableException
451

452
Queryable record table errors during table query operations.
453

454
```java { .api }
455
public class QueryableRecordTableException extends SiddhiException {
456
    public QueryableRecordTableException(String message);
457
    public QueryableRecordTableException(String message, Throwable cause);
458
}
459
```
460

461
## Exception Handling Patterns
462

463
### Centralized Exception Handling
464

465
```java
466
// Global exception handler for Siddhi applications
467
public class SiddhiExceptionHandler {
468
    
469
    public void handleException(Exception e, String context) {
470
        if (e instanceof SiddhiAppCreationException) {
471
            handleCreationError((SiddhiAppCreationException) e, context);
472
        } else if (e instanceof SiddhiAppRuntimeException) {
473
            handleRuntimeError((SiddhiAppRuntimeException) e, context);
474
        } else if (e instanceof PersistenceStoreException) {
475
            handlePersistenceError((PersistenceStoreException) e, context);
476
        } else if (e instanceof ConnectionUnavailableException) {
477
            handleConnectionError((ConnectionUnavailableException) e, context);
478
        } else {
479
            handleGenericError(e, context);
480
        }
481
    }
482
    
483
    private void handleCreationError(SiddhiAppCreationException e, String context) {
484
        // Log creation error with context
485
        logger.error("Siddhi app creation failed in context: {}", context, e);
486
        
487
        // Notify administrators
488
        alertService.sendAlert("Siddhi app creation failed", e.getMessage());
489
        
490
        // Attempt fallback configuration
491
        tryFallbackConfiguration(context);
492
    }
493
    
494
    private void handleRuntimeError(SiddhiAppRuntimeException e, String context) {
495
        // Log runtime error
496
        logger.error("Siddhi runtime error in context: {}", context, e);
497
        
498
        // Check if recovery is possible
499
        if (isRecoverable(e)) {
500
            attemptRecovery(context);
501
        } else {
502
            initiateFailover(context);
503
        }
504
    }
505
    
506
    private boolean isRecoverable(SiddhiAppRuntimeException e) {
507
        // Determine if error is recoverable based on cause
508
        Throwable cause = e.getCause();
509
        return !(cause instanceof OutOfMemoryError) && 
510
               !(cause instanceof StackOverflowError);
511
    }
512
}
513
```
514

515
### Retry and Circuit Breaker Pattern
516

517
```java
518
// Resilient operation execution with retry and circuit breaker
519
public class ResilientSiddhiOperations {
520
    private final CircuitBreaker circuitBreaker;
521
    private final RetryPolicy retryPolicy;
522
    
523
    public void executeWithResilience(Runnable operation) {
524
        try {
525
            circuitBreaker.executeSupplier(() -> {
526
                retryPolicy.execute(() -> {
527
                    operation.run();
528
                    return null;
529
                });
530
                return null;
531
            });
532
        } catch (SiddhiException e) {
533
            // Handle specific Siddhi exceptions
534
            handleSiddhiException(e);
535
        } catch (Exception e) {
536
            // Handle other exceptions
537
            handleGenericException(e);
538
        }
539
    }
540
    
541
    private void handleSiddhiException(SiddhiException e) {
542
        if (e instanceof ConnectionUnavailableException) {
543
            // Switch to offline mode
544
            switchToOfflineMode();
545
        } else if (e instanceof PersistenceStoreException) {
546
            // Use alternative storage
547
            switchToAlternativeStorage();
548
        }
549
    }
550
}
551
```
552

553
## Types
554

555
```java { .api }
556
public interface ExceptionHandler<T> {
557
    void handle(T object, Exception exception);
558
}
559

560
public interface ExceptionListener {
561
    void exceptionThrown(Exception exception);
562
}
563

564
public interface RetryPolicy {
565
    <T> T execute(Callable<T> callable) throws Exception;
566
    RetryPolicy withMaxRetries(int maxRetries);
567
    RetryPolicy withDelay(Duration delay);
568
}
569

570
public interface CircuitBreaker {
571
    <T> T executeSupplier(Supplier<T> supplier) throws Exception;
572
    void open();
573
    void close();
574
    boolean isOpen();
575
}
576
```