0
# Annotation Processors
1

2
Compile-time validation framework that ensures extension annotations comply with Siddhi's requirements. The processor system validates all annotation elements, enforces naming conventions, and provides specialized validation rules for different extension types.
3

4
## Capabilities
5

6
### SiddhiAnnotationProcessor
7

8
The main annotation processor that orchestrates validation for all Siddhi extension annotations during compilation.
9

10
```java { .api }
11
/**
12
 * The annotation processor for siddhi extension annotation validation.
13
 * Validates @Extension, @Parameter, @ReturnAttribute, @SystemParameter and @Example annotations.
14
 * 
15
 * Extends javax.annotation.processing.AbstractProcessor
16
 */
17
public class SiddhiAnnotationProcessor extends AbstractProcessor {
18
    
19
    /**
20
     * Initialize the processor with the processing environment.
21
     * 
22
     * @param env - Processing environment providing access to facilities
23
     */
24
    public synchronized void init(ProcessingEnvironment env);
25
    
26
    /**
27
     * Process annotations found in the current compilation round.
28
     * 
29
     * @param annotations - Set of annotation types to process
30
     * @param roundEnv - Environment for information about the current round
31
     * @return false - This processor only validates, doesn't claim annotations
32
     */
33
    public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv);
34
    
35
    /**
36
     * Get the set of annotation types supported by this processor.
37
     * 
38
     * @return Set of supported annotation type names
39
     */
40
    public Set<String> getSupportedAnnotationTypes();
41
    
42
    /**
43
     * Get the latest source version supported by this processor.
44
     * 
45
     * @return SourceVersion.RELEASE_8
46
     */
47
    public SourceVersion getSupportedSourceVersion();
48
    
49
    /**
50
     * Report a build error with a message and element context.
51
     * 
52
     * @param message - Error message to display
53
     * @param element - Source element where error occurred
54
     */
55
    public void showBuildError(String message, Element element);
56
}
57
```
58

59
**Supported Extension Types:**
60
- Sink extensions
61
- SinkMapper extensions  
62
- Source extensions
63
- SourceMapper extensions
64
- FunctionExecutor extensions
65
- AggregationAttribute extensions
66
- StreamProcessor extensions
67
- StreamFunctionProcessor extensions
68
- WindowProcessor extensions
69
- Store extensions
70
- DistributionStrategy extensions
71
- Script extensions
72
- IncrementalAggregationAttribute extensions
73

74
### AbstractAnnotationProcessor
75

76
Base class providing common validation logic and patterns for all extension-specific processors.
77

78
```java { .api }
79
/**
80
 * Parent class for extension annotation validation processors.
81
 * Provides common validation patterns and regex-based validation rules.
82
 */
83
public abstract class AbstractAnnotationProcessor {
84
    
85
    /** Regex pattern for validating core package names */
86
    protected static final Pattern CORE_PACKAGE_PATTERN; // ^org.wso2.siddhi.core.
87
    
88
    /** Regex pattern for validating parameter names in dot notation */
89
    protected static final Pattern PARAMETER_NAME_PATTERN; // ^[a-z][a-z0-9]*(\\.[a-z][a-z0-9]*)*$
90
    
91
    /** Regex pattern for validating camelCase naming convention */
92
    protected static final Pattern CAMEL_CASE_PATTERN; // ^(([a-z][a-z0-9]+)([A-Z]{0,1}[a-z0-9]*)*)$
93
    
94
    /** Full name of the extension class being validated */
95
    protected String extensionClassFullName;
96
    
97
    /**
98
     * Constructor for annotation processor.
99
     * 
100
     * @param extensionClassFullName - Full name of extension class
101
     */
102
    public AbstractAnnotationProcessor(String extensionClassFullName);
103
    
104
    /**
105
     * Basic @Extension annotation elements validation.
106
     * 
107
     * @param name - Extension name to validate
108
     * @param description - Extension description to validate  
109
     * @param namespace - Extension namespace to validate
110
     * @throws AnnotationValidationException - When validation rules are violated
111
     */
112
    public void basicParameterValidation(String name, String description, String namespace) 
113
            throws AnnotationValidationException;
114
    
115
    /**
116
     * Validate @Extension parameter definitions.
117
     * 
118
     * @param parameters - Parameter array to validate
119
     * @throws AnnotationValidationException - When validation rules are violated
120
     */
121
    public void parameterValidation(Parameter[] parameters) throws AnnotationValidationException;
122
    
123
    /**
124
     * Validate @Extension return attribute definitions.
125
     * 
126
     * @param returnAttributes - Return attributes array to validate
127
     * @throws AnnotationValidationException - When validation rules are violated
128
     */
129
    public void returnAttributesValidation(ReturnAttribute[] returnAttributes) 
130
            throws AnnotationValidationException;
131
    
132
    /**
133
     * Validate @Extension system parameter definitions.
134
     * 
135
     * @param systemParameters - System parameters array to validate
136
     * @throws AnnotationValidationException - When validation rules are violated
137
     */
138
    public void systemParametersValidation(SystemParameter[] systemParameters) 
139
            throws AnnotationValidationException;
140
    
141
    /**
142
     * Validate @Extension example definitions.
143
     * 
144
     * @param examples - Examples array to validate
145
     * @throws AnnotationValidationException - When validation rules are violated
146
     */
147
    public void examplesValidation(Example[] examples) throws AnnotationValidationException;
148
}
149
```
150

151
### Extension-Specific Processors
152

153
Specialized processors that extend AbstractAnnotationProcessor with custom validation logic for specific extension types.
154

155
#### FunctionExecutorValidationAnnotationProcessor
156

157
```java { .api }
158
/**
159
 * Validation processor for Function Executor extensions.
160
 * Enforces function-specific rules including single return attribute and no dynamic parameters.
161
 */
162
public class FunctionExecutorValidationAnnotationProcessor extends AbstractAnnotationProcessor {
163
    
164
    public FunctionExecutorValidationAnnotationProcessor(String extensionClassFullName);
165
    
166
    /**
167
     * Override parameter validation to disallow dynamic parameters.
168
     * Dynamic parameters are only allowed for Sink and SinkMapper extensions.
169
     */
170
    @Override
171
    public void parameterValidation(Parameter[] parameters) throws AnnotationValidationException;
172
    
173
    /**
174
     * Override return attribute validation to enforce single return attribute with empty name.
175
     * Function executors must have exactly one return attribute without a name.
176
     */
177
    @Override
178
    public void returnAttributesValidation(ReturnAttribute[] returnAttributes) 
179
            throws AnnotationValidationException;
180
}
181
```
182

183
#### Other Specialized Processors
184

185
```java { .api }
186
/**
187
 * Validation processors for specific extension types, each with custom rules:
188
 */
189

190
// Sink extensions
191
public class SinkValidationAnnotationProcessor extends AbstractAnnotationProcessor;
192

193
// SinkMapper extensions  
194
public class SinkMapperValidationAnnotationProcessor extends AbstractAnnotationProcessor;
195

196
// Source extensions
197
public class SourceValidationAnnotationProcessor extends AbstractAnnotationProcessor;
198

199
// SourceMapper extensions
200
public class SourceMapperValidationAnnotationProcessor extends AbstractAnnotationProcessor;
201

202
// AggregationAttribute extensions
203
public class AggregationAttributeValidationAnnotationProcessor extends AbstractAnnotationProcessor;
204

205
// StreamProcessor extensions
206
public class StreamProcessorValidationAnnotationProcessor extends AbstractAnnotationProcessor;
207

208
// StreamFunctionProcessor extensions
209
public class StreamFunctionProcessorValidationAnnotationProcessor extends AbstractAnnotationProcessor;
210

211
// WindowProcessor extensions
212
public class WindowProcessorValidationAnnotationProcessor extends AbstractAnnotationProcessor;
213

214
// Store extensions
215
public class StoreValidationAnnotationProcessor extends AbstractAnnotationProcessor;
216

217
// DistributionStrategy extensions
218
public class DistributionStrategyValidationAnnotationProcessor extends AbstractAnnotationProcessor;
219

220
// Script extensions
221
public class ScriptValidationAnnotationProcessor extends AbstractAnnotationProcessor;
222

223
// IncrementalAggregationAttribute extensions
224
public class IncrementalAggregationAttributeValidationAnnotationProcessor extends AbstractAnnotationProcessor;
225
```
226

227
## Usage Examples
228

229
### Annotation Processor Registration
230

231
The processors are automatically registered through the Java annotation processing mechanism:
232

233
**META-INF/services/javax.annotation.processing.Processor:**
234
```text
235
org.wso2.siddhi.annotation.processor.SiddhiAnnotationProcessor
236
org.atteo.classindex.processor.ClassIndexProcessor
237
```
238

239
### Compilation Integration
240

241
The processors run automatically during compilation when the siddhi-annotations JAR is on the classpath:
242

243
```xml
244
<plugin>
245
    <groupId>org.apache.maven.plugins</groupId>
246
    <artifactId>maven-compiler-plugin</artifactId>
247
    <configuration>
248
        <!-- Processors run automatically unless disabled -->
249
        <compilerArgument>-proc:none</compilerArgument> <!-- To disable -->
250
    </configuration>
251
</plugin>
252
```
253

254
### Validation Error Examples
255

256
**Missing Extension Name:**
257
```
258
The @Extension -> name annotated in class com.example.MyExtension is null or empty.
259
```
260

261
**Invalid Parameter Name Format:**
262
```
263
The @Extension -> @Parameter -> name 'InvalidName' annotated in class com.example.MyExtension is not in proper format 'abc.def.ghi'.
264
```
265

266
**Function Executor with Multiple Return Attributes:**
267
```
268
Only one @Extension -> @ReturnAttribute can be annotated in class com.example.MyFunction.
269
```
270

271
**Dynamic Parameter in Non-Sink Extension:**
272
```
273
The @Extension -> @Parameter -> name:param -> dynamic property cannot be true annotated in class com.example.MyProcessor. Only classes extending Sink and SinkMapper can have dynamic parameters.
274
```
275

276
## Validation Flow
277

278
1. **Discovery**: SiddhiAnnotationProcessor discovers all @Extension annotated classes
279
2. **Superclass Matching**: Determines which specialized processor to use based on extension superclass
280
3. **Basic Validation**: Validates extension name, description, namespace
281
4. **Element Validation**: Validates parameters, return attributes, system parameters, examples
282
5. **Type-Specific Rules**: Applies extension-type-specific validation rules
283
6. **Error Reporting**: Reports compilation errors for any validation failures
284

285
The validation ensures that all Siddhi extensions are properly defined and can be safely loaded and used by the Siddhi runtime engine.