0
# Core Annotations
1

2
Primary annotations for marking and describing Siddhi extensions. These annotations provide the metadata needed for Siddhi to discover, validate, and utilize custom extensions at both compile-time and runtime.
3

4
## Capabilities
5

6
### @Extension Annotation
7

8
The main annotation that marks a class as a Siddhi extension, providing essential metadata including name, namespace, description, and associated elements.
9

10
```java { .api }
11
/**
12
 * Annotation for specifying it as a Siddhi Extension.
13
 * Must be applied to classes that extend Siddhi extension superclasses.
14
 * 
15
 * @Target ElementType.TYPE
16
 * @Retention RetentionPolicy.RUNTIME
17
 * @IndexAnnotated
18
 */
19
@interface Extension {
20
    /** Extension name - required for non-core extensions */
21
    String name() default "";
22
    
23
    /** Extension namespace - required for non-core extensions */
24
    String namespace() default "";
25
    
26
    /** Description of the extension functionality - required */
27
    String description() default "";
28
    
29
    /** Array of parameter definitions */
30
    Parameter[] parameters() default {};
31
    
32
    /** Array of system parameter definitions */
33
    SystemParameter[] systemParameter() default {};
34
    
35
    /** Array of return attribute definitions */
36
    ReturnAttribute[] returnAttributes() default {};
37
    
38
    /** Array of usage examples */
39
    Example[] examples() default {};
40
}
41
```
42

43
**Usage Example:**
44

45
```java
46
import org.wso2.siddhi.annotation.util.DataType;
47

48
@Extension(
49
    name = "customFunction",
50
    namespace = "custom",
51
    description = "Performs custom data processing on input values.",
52
    parameters = {
53
        @Parameter(name = "input", 
54
                  type = {DataType.STRING}, 
55
                  description = "Input string to process"),
56
        @Parameter(name = "mode", 
57
                  type = {DataType.STRING}, 
58
                  description = "Processing mode",
59
                  optional = true,
60
                  defaultValue = "default")
61
    },
62
    returnAttributes = @ReturnAttribute(
63
        type = {DataType.STRING}, 
64
        description = "Processed output string"
65
    ),
66
    examples = @Example(
67
        syntax = "from inputStream#custom:customFunction(data, 'advanced') select result insert into outputStream;",
68
        description = "Process input data using advanced mode."
69
    )
70
)
71
public class CustomFunction extends FunctionExecutor {
72
    // Implementation
73
}
74
```
75

76
### @Parameter Annotation
77

78
Defines parameters for Siddhi extensions, including type information, validation rules, and optional/default value specifications.
79

80
```java { .api }
81
/**
82
 * Annotation for storing the parameters of a Siddhi Extension.
83
 * Used within @Extension parameter arrays.
84
 * 
85
 * @Retention RetentionPolicy.RUNTIME
86
 * @Target {} - No direct target, used within @Extension
87
 */
88
@interface Parameter {
89
    /** Parameter name in dot notation format (e.g., "param.subparam") */
90
    String name() default "";
91
    
92
    /** Array of supported data types for this parameter */
93
    DataType[] type() default {};
94
    
95
    /** Description of the parameter's purpose and usage */
96
    String description() default "";
97
    
98
    /** Whether this parameter is optional (default: false) */
99
    boolean optional() default false;
100
    
101
    /** Whether this parameter supports dynamic values (Sink/SinkMapper only) */
102
    boolean dynamic() default false;
103
    
104
    /** Default value for optional parameters */
105
    String defaultValue() default "";
106
}
107
```
108

109
**Usage Examples:**
110

111
```java
112
// Required parameter
113
@Parameter(name = "host", 
114
          type = {DataType.STRING}, 
115
          description = "Server hostname")
116

117
// Optional parameter with default
118
@Parameter(name = "port", 
119
          type = {DataType.INT}, 
120
          description = "Server port number",
121
          optional = true,
122
          defaultValue = "8080")
123

124
// Dynamic parameter (Sink/SinkMapper only)
125
@Parameter(name = "headers", 
126
          type = {DataType.STRING}, 
127
          description = "HTTP headers",
128
          dynamic = true)
129
```
130

131
### @ReturnAttribute Annotation
132

133
Defines attributes returned by stream processors, specifying their names, types, and descriptions for proper data flow handling.
134

135
```java { .api }
136
/**
137
 * Annotation for storing additional attributes returned by a stream processor.
138
 * Used within @Extension returnAttributes arrays.
139
 * 
140
 * @Retention RetentionPolicy.RUNTIME
141
 * @Target {} - No direct target, used within @Extension
142
 */
143
@interface ReturnAttribute {
144
    /** Name of the return attribute (camelCase format) */
145
    String name() default "";
146
    
147
    /** Array of possible data types for this attribute */
148
    DataType[] type() default {};
149
    
150
    /** Description of the attribute's meaning and usage */
151
    String description() default "";
152
}
153
```
154

155
**Usage Examples:**
156

157
```java
158
// Single return attribute
159
@ReturnAttribute(name = "average", 
160
                type = {DataType.DOUBLE}, 
161
                description = "Calculated average value")
162

163
// Multiple return attributes
164
returnAttributes = {
165
    @ReturnAttribute(name = "sum", 
166
                    type = {DataType.LONG, DataType.DOUBLE}, 
167
                    description = "Sum of all values"),
168
    @ReturnAttribute(name = "count", 
169
                    type = {DataType.LONG}, 
170
                    description = "Number of values processed")
171
}
172

173
// Function executor (no name, single attribute)
174
@ReturnAttribute(type = {DataType.STRING}, 
175
                description = "Processed string result")
176
```
177

178
### @SystemParameter Annotation
179

180
Defines system-level configuration parameters that affect extension behavior at the system level, with predefined possible values.
181

182
```java { .api }
183
/**
184
 * Annotation for storing the system parameters of a Siddhi Extension.
185
 * Used within @Extension systemParameter arrays.
186
 * 
187
 * @Retention RetentionPolicy.RUNTIME
188
 * @Target {} - No direct target, used within @Extension
189
 */
190
@interface SystemParameter {
191
    /** System parameter name */
192
    String name() default "";
193
    
194
    /** Description of the system parameter's purpose */
195
    String description() default "";
196
    
197
    /** Default value for the system parameter */
198
    String defaultValue() default "";
199
    
200
    /** Array of possible values for this parameter */
201
    String[] possibleParameters() default {};
202
}
203
```
204

205
**Usage Example:**
206

207
```java
208
@SystemParameter(
209
    name = "threading.mode",
210
    description = "Threading mode for parallel processing",
211
    defaultValue = "single",
212
    possibleParameters = {"single", "multi", "adaptive"}
213
)
214
```
215

216
### @Example Annotation
217

218
Provides usage examples for extensions, including syntax and descriptive explanations to help users understand proper usage patterns.
219

220
```java { .api }
221
/**
222
 * Optional annotation for storing examples for a Siddhi Extension.
223
 * Used within @Extension examples arrays.
224
 * 
225
 * @Retention RetentionPolicy.RUNTIME
226
 * @Target {} - No direct target, used within @Extension
227
 */
228
@interface Example {
229
    /** Example syntax showing how to use the extension */
230
    String syntax() default "";
231
    
232
    /** Description explaining what the example demonstrates */
233
    String description() default "";
234
}
235
```
236

237
**Usage Examples:**
238

239
```java
240
// Single example
241
@Example(
242
    syntax = "from streamA#window.time(10 sec) select * insert into streamB;",
243
    description = "Process events within a 10-second time window."
244
)
245

246
// Multiple examples
247
examples = {
248
    @Example(
249
        syntax = "from dataStream#custom:transform('upper') select result insert into output;",
250
        description = "Transform text to uppercase."
251
    ),
252
    @Example(
253
        syntax = "from dataStream#custom:transform('lower') select result insert into output;",
254
        description = "Transform text to lowercase."
255
    )
256
}
257
```
258

259
## Validation Rules
260

261
All core annotations are subject to compile-time validation:
262

263
### @Extension Validation
264
- `name` cannot be empty for non-core extensions
265
- `description` cannot be empty
266
- `namespace` cannot be empty for non-core extensions
267
- Must have at least one `@Example`
268
- Class must extend a valid Siddhi extension superclass
269

270
### @Parameter Validation
271
- `name` cannot be empty and must follow dot notation pattern: `^[a-z][a-z0-9]*(\\.[a-z][a-z0-9]*)*$`
272
- `description` cannot be empty
273
- `type` array cannot be empty
274
- If `optional` is true, `defaultValue` cannot be empty
275
- `dynamic` can only be true for Sink and SinkMapper extensions
276

277
### @ReturnAttribute Validation
278
- `name` must follow camelCase pattern: `^(([a-z][a-z0-9]+)([A-Z]{0,1}[a-z0-9]*)*)$`
279
- `description` cannot be empty
280
- `type` array cannot be empty
281
- Function executors can have only one return attribute with empty name
282

283
### @SystemParameter Validation
284
- `name` cannot be empty
285
- `description` cannot be empty
286
- `defaultValue` cannot be empty
287
- `possibleParameters` array cannot be empty
288

289
### @Example Validation
290
- `syntax` cannot be empty
291
- `description` cannot be empty
292
- At least one example is required per extension