0
# Siddhi Core
1

2
Siddhi Core is a high-performing Complex Event Processing (CEP) engine Java library that provides comprehensive stream processing capabilities. It enables real-time processing of data streams, detection of complex conditions through Streaming SQL, and triggering of responsive actions. Built for high-performance scenarios, Siddhi Core can process 300,000+ events per second and is designed to be lightweight (<2MB) and embeddable across diverse platforms from enterprise systems to Android and Raspberry Pi devices.
3

4
## Package Information
5

6
- **Package Name**: org.wso2.siddhi:siddhi-core
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Version**: 4.5.11
10
- **Installation**: 
11
  ```xml
12
  <dependency>
13
      <groupId>org.wso2.siddhi</groupId>
14
      <artifactId>siddhi-core</artifactId>
15
      <version>4.5.11</version>
16
  </dependency>
17
  ```
18

19
## Core Imports
20

21
```java
22
import org.wso2.siddhi.core.SiddhiManager;
23
import org.wso2.siddhi.core.SiddhiAppRuntime;
24
import org.wso2.siddhi.core.stream.input.InputHandler;
25
import org.wso2.siddhi.core.stream.output.StreamCallback;
26
import org.wso2.siddhi.core.query.output.callback.QueryCallback;
27
import org.wso2.siddhi.core.event.Event;
28
import org.wso2.siddhi.core.config.SiddhiContext;
29
```
30

31
## Basic Usage
32

33
```java
34
// Create Siddhi Manager
35
SiddhiManager siddhiManager = new SiddhiManager();
36

37
// Create Siddhi App with streaming SQL
38
String siddhiApp = "define stream StockStream (symbol string, price float, volume long); " +
39
                  "from StockStream[price > 100] select symbol, price insert into HighPriceStocks;";
40
SiddhiAppRuntime siddhiAppRuntime = siddhiManager.createSiddhiAppRuntime(siddhiApp);
41

42
// Add callback to receive results
43
siddhiAppRuntime.addCallback("HighPriceStocks", new StreamCallback() {
44
    @Override
45
    public void receive(Event[] events) {
46
        for (Event event : events) {
47
            System.out.println("High price stock: " + event);
48
        }
49
    }
50
});
51

52
// Get input handler and start runtime
53
InputHandler stockStream = siddhiAppRuntime.getInputHandler("StockStream");
54
siddhiAppRuntime.start();
55

56
// Send events
57
stockStream.send(new Object[]{"IBM", 150.0f, 100L});
58
stockStream.send(new Object[]{"MSFT", 75.0f, 200L});
59

60
// Shutdown
61
siddhiAppRuntime.shutdown();
62
siddhiManager.shutdown();
63
```
64

65
## Architecture
66

67
Siddhi Core follows a modular architecture with these key components:
68

69
- **SiddhiManager**: Entry point for managing Siddhi applications and global configurations
70
- **SiddhiAppRuntime**: Runtime environment for individual Siddhi applications with lifecycle management
71
- **Event Processing**: High-performance event handling with disruptor-based architecture
72
- **Stream Processing**: Input handlers, processors, and output callbacks for real-time data flow
73
- **Query Engine**: Streaming SQL processing with pattern matching and complex event detection
74
- **Extensions**: Pluggable architecture for custom sources, sinks, functions, and processors
75
- **State Management**: Persistence and snapshotting capabilities for fault tolerance
76

77
## Capabilities
78

79
### Core Management
80

81
Primary interfaces for creating and managing Siddhi applications with full lifecycle control.
82

83
```java { .api }
84
public class SiddhiManager {
85
    public SiddhiManager();
86
    public SiddhiAppRuntime createSiddhiAppRuntime(String siddhiApp);
87
    public SiddhiAppRuntime getSiddhiAppRuntime(String siddhiAppName);
88
    public void shutdown();
89
}
90

91
public class SiddhiAppRuntime {
92
    public String getName();
93
    public void start();
94
    public void shutdown();
95
    public InputHandler getInputHandler(String streamId);
96
}
97
```
98

99
[Core Management](./core-management.md)
100

101
### Event Handling
102

103
Event classes and input mechanisms for processing streaming data with high-performance capabilities.
104

105
```java { .api }
106
public class Event {
107
    public Event(long timestamp, Object[] data);
108
    public long getTimestamp();
109
    public Object[] getData();
110
}
111

112
public class InputHandler {
113
    public void send(Object[] data);
114
    public void send(long timestamp, Object[] data);
115
    public void send(Event event);
116
}
117
```
118

119
[Event Handling](./event-handling.md)
120

121
### Queries and Callbacks
122

123
Query processing and callback mechanisms for receiving processed results from streaming SQL operations.
124

125
```java { .api }
126
public abstract class StreamCallback {
127
    public abstract void receive(Event[] events);
128
    public void setStreamId(String streamId);
129
}
130

131
public abstract class QueryCallback {
132
    public abstract void receive(long timestamp, Event[] inEvents, Event[] removeEvents);
133
}
134
```
135

136
[Queries and Callbacks](./queries-and-callbacks.md)
137

138
### Aggregations
139

140
Incremental aggregation processing with support for different time durations and distributed processing.
141

142
```java { .api }
143
public class AggregationRuntime {
144
    // Manages incremental aggregations across time durations
145
    // Supports distributed aggregation processing
146
    // Provides incremental data purging capabilities
147
}
148
```
149

150
[Aggregations](./aggregations.md)
151

152
### Persistence
153

154
State management and persistence capabilities for fault tolerance and recovery scenarios.
155

156
```java { .api }
157
public interface PersistenceStore {
158
    void save(String siddhiAppName, String revision, byte[] snapshot);
159
    byte[] load(String siddhiAppName, String revision);
160
}
161

162
public class SiddhiAppRuntime {
163
    public PersistenceReference persist();
164
    public byte[] snapshot();
165
    public void restore(byte[] snapshot);
166
}
167
```
168

169
[Persistence](./persistence.md)
170

171
### Extensions
172

173
Extension points for creating custom sources, sinks, functions, and processors to extend Siddhi capabilities.
174

175
```java { .api }
176
public interface Source {
177
    // Interface for creating custom input sources
178
}
179

180
public interface Sink {
181
    // Interface for creating custom output sinks
182
}
183

184
public interface FunctionExecutor {
185
    // Interface for custom functions
186
}
187
```
188

189
[Extensions](./extensions.md)
190

191
### Statistics
192

193
Monitoring and statistics interfaces for tracking performance, throughput, and resource usage.
194

195
```java { .api }
196
public enum Level {
197
    OFF, BASIC, DETAIL
198
}
199

200
public class SiddhiAppRuntime {
201
    public Level getRootMetricsLevel();
202
    public void enableStats(Level level);
203
}
204
```
205

206
[Statistics](./statistics.md)
207

208
### Exceptions
209

210
Comprehensive exception handling for various error scenarios in stream processing operations.
211

212
```java { .api }
213
public class SiddhiAppCreationException extends SiddhiException {
214
    // Thrown during Siddhi app creation errors
215
}
216

217
public class SiddhiAppRuntimeException extends SiddhiException {
218
    // Runtime errors in Siddhi app execution
219
}
220
```
221

222
[Exceptions](./exceptions.md)
223

224
## Common Types
225

226
```java { .api }
227
public interface ComplexEvent {
228
    // Interface for complex events used internally
229
}
230

231
public class ComplexEventChunk<T extends ComplexEvent> {
232
    // Container for chaining complex events together
233
}
234

235
public interface Processor {
236
    void process(ComplexEventChunk complexEventChunk);
237
    Processor getNextProcessor();
238
    void setNextProcessor(Processor processor);
239
}
240
```