0
# Siddhi Annotations
1

2
Siddhi Annotations provides comprehensive annotation support for the Siddhi Complex Event Processing Engine, enabling developers to define and validate custom extensions through a standardized annotation framework. It includes core annotations for marking Siddhi extensions, compile-time validation processors, and runtime discovery mechanisms through ClassIndex integration.
3

4
## Package Information
5

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

18
## Core Imports
19

20
```java
21
import org.wso2.siddhi.annotation.Extension;
22
import org.wso2.siddhi.annotation.Parameter;
23
import org.wso2.siddhi.annotation.ReturnAttribute;
24
import org.wso2.siddhi.annotation.SystemParameter;
25
import org.wso2.siddhi.annotation.Example;
26
import org.wso2.siddhi.annotation.util.DataType;
27
```
28

29
## Basic Usage
30

31
```java
32
import org.wso2.siddhi.annotation.*;
33
import org.wso2.siddhi.annotation.util.DataType;
34

35
@Extension(
36
    name = "sum",
37
    namespace = "math",
38
    description = "Calculates the sum of numeric values.",
39
    parameters = {
40
        @Parameter(name = "value", 
41
                  type = {DataType.INT, DataType.LONG, DataType.DOUBLE}, 
42
                  description = "Numeric value to be summed")
43
    },
44
    returnAttributes = @ReturnAttribute(
45
        name = "sum", 
46
        type = {DataType.LONG, DataType.DOUBLE}, 
47
        description = "Sum of the numeric values"
48
    ),
49
    examples = @Example(
50
        syntax = "from inputStream#math:sum(value) select sum insert into outputStream;",
51
        description = "This calculates the sum of 'value' from inputStream."
52
    )
53
)
54
public class SumFunction extends FunctionExecutor {
55
    // Implementation details
56
}
57
```
58

59
## Architecture
60

61
The Siddhi Annotations framework is built around several key components:
62

63
- **Core Annotations**: Five primary annotations (@Extension, @Parameter, @ReturnAttribute, @SystemParameter, @Example) that define extension metadata
64
- **Validation Framework**: Compile-time annotation processors that validate extension definitions against Siddhi's requirements
65
- **Type System**: DataType enum providing standardized type definitions for parameters and return values
66
- **Runtime Discovery**: ClassIndex integration enabling automatic discovery of annotated extensions
67
- **Extension Types**: Support for 11+ different Siddhi extension types with specific validation rules
68

69
## Capabilities
70

71
### Core Annotations
72

73
Primary annotations for marking and describing Siddhi extensions, including the main @Extension annotation and supporting annotations for parameters, return attributes, system parameters, and usage examples.
74

75
```java { .api }
76
@interface Extension {
77
    String name() default "";
78
    String namespace() default "";
79
    String description() default "";
80
    Parameter[] parameters() default {};
81
    SystemParameter[] systemParameter() default {};
82
    ReturnAttribute[] returnAttributes() default {};
83
    Example[] examples() default {};
84
}
85
```
86

87
[Core Annotations](./core-annotations.md)
88

89
### Annotation Processors
90

91
Compile-time validation framework that ensures extension annotations comply with Siddhi's requirements, with specialized processors for different extension types and comprehensive validation rules.
92

93
```java { .api }
94
public class SiddhiAnnotationProcessor extends AbstractProcessor {
95
    public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv);
96
}
97

98
public abstract class AbstractAnnotationProcessor {
99
    protected void basicParameterValidation(String name, String description, String namespace) throws AnnotationValidationException;
100
    protected void parameterValidation(Parameter[] parameters) throws AnnotationValidationException;
101
    protected void returnAttributesValidation(ReturnAttribute[] returnAttributes) throws AnnotationValidationException;
102
}
103
```
104

105
[Annotation Processors](./annotation-processors.md)
106

107
### Utility Classes
108

109
Supporting classes including data type definitions, validation exceptions, and constants for extension superclasses and namespaces.
110

111
```java { .api }
112
public enum DataType {
113
    STRING, INT, LONG, FLOAT, DOUBLE, BOOL, OBJECT, TIME
114
}
115

116
public class AnnotationValidationException extends Exception {
117
    public AnnotationValidationException(String message);
118
    public AnnotationValidationException(String message, Throwable throwable);
119
    public AnnotationValidationException(Throwable throwable);
120
}
121
```
122

123
[Utility Classes](./utility-classes.md)
124

125
## Types
126

127
### Core Annotation Types
128

129
```java { .api }
130
@interface Parameter {
131
    String name() default "";
132
    DataType[] type() default {};
133
    String description() default "";
134
    boolean optional() default false;
135
    boolean dynamic() default false;
136
    String defaultValue() default "";
137
}
138

139
@interface ReturnAttribute {
140
    String name() default "";
141
    DataType[] type() default {};
142
    String description() default "";
143
}
144

145
@interface SystemParameter {
146
    String name() default "";
147
    String description() default "";
148
    String defaultValue() default "";
149
    String[] possibleParameters() default {};
150
}
151

152
@interface Example {
153
    String syntax() default "";
154
    String description() default "";
155
}
156
```