0
# Utility Classes
1

2
Supporting classes that provide data type definitions, validation exceptions, and constants used throughout the Siddhi annotation framework. These utilities enable proper type validation, error handling, and extension classification.
3

4
## Capabilities
5

6
### DataType Enum
7

8
Standardized data type definitions used in @Parameter and @ReturnAttribute annotations to specify supported data types for extension parameters and return values.
9

10
```java { .api }
11
/**
12
 * Enum types used in @Parameter and @ReturnAttribute annotations.
13
 * Provides standardized data type definitions for Siddhi extensions.
14
 */
15
public enum DataType {
16
    /** String data type for text values */
17
    STRING,
18
    
19
    /** Integer data type for 32-bit signed integers */
20
    INT,
21
    
22
    /** Long data type for 64-bit signed integers */
23
    LONG,
24
    
25
    /** Float data type for 32-bit floating point numbers */
26
    FLOAT,
27
    
28
    /** Double data type for 64-bit floating point numbers */
29
    DOUBLE,
30
    
31
    /** Boolean data type for true/false values */
32
    BOOL,
33
    
34
    /** Object data type for arbitrary Java objects */
35
    OBJECT,
36
    
37
    /** Time data type for temporal values */
38
    TIME
39
}
40
```
41

42
**Usage Examples:**
43

44
```java
45
// Single data type
46
@Parameter(name = "count", type = {DataType.INT})
47

48
// Multiple allowed data types
49
@Parameter(name = "value", type = {DataType.INT, DataType.LONG, DataType.DOUBLE})
50

51
// Return attribute with specific type
52
@ReturnAttribute(type = {DataType.STRING}, description = "Processed result")
53

54
// Flexible numeric parameter
55
@Parameter(name = "threshold", 
56
          type = {DataType.FLOAT, DataType.DOUBLE}, 
57
          description = "Threshold value for comparison")
58
```
59

60
### AnnotationValidationException
61

62
Custom exception class for annotation validation errors, providing structured error reporting during compile-time validation.
63

64
```java { .api }
65
/**
66
 * Custom exception for annotation validation errors.
67
 * Thrown by AbstractAnnotationProcessor during compile-time validation.
68
 * 
69
 * Extends java.lang.Exception
70
 */
71
public class AnnotationValidationException extends Exception {
72
    
73
    /**
74
     * Constructs a new exception with the specified detail message.
75
     * 
76
     * @param message - Detail message explaining the validation error
77
     */
78
    public AnnotationValidationException(String message);
79
    
80
    /**
81
     * Constructs a new exception with the specified detail message and cause.
82
     * 
83
     * @param message - Detail message explaining the validation error
84
     * @param throwable - Underlying cause of the validation error
85
     */
86
    public AnnotationValidationException(String message, Throwable throwable);
87
    
88
    /**
89
     * Constructs a new exception with the specified cause.
90
     * 
91
     * @param throwable - Underlying cause of the validation error
92
     */
93
    public AnnotationValidationException(Throwable throwable);
94
}
95
```
96

97
**Usage Example:**
98

99
```java
100
public void validateParameter(Parameter param) throws AnnotationValidationException {
101
    if (param.name().isEmpty()) {
102
        throw new AnnotationValidationException(
103
            "Parameter name cannot be empty in extension: " + extensionClass
104
        );
105
    }
106
    
107
    if (param.type().length == 0) {
108
        throw new AnnotationValidationException(
109
            "Parameter type array cannot be empty for: " + param.name()
110
        );
111
    }
112
}
113
```
114

115
### AnnotationConstants
116

117
Constants class containing superclass names and namespace definitions used for extension classification and validation.
118

119
```java { .api }
120
/**
121
 * Siddhi annotation constants class.
122
 * Contains superclass names and namespace constants for extension validation.
123
 */
124
public class AnnotationConstants {
125
    
126
    // Extension Superclass Constants
127
    /** Superclass name for SinkMapper extensions */
128
    public static final String SINK_MAPPER_SUPER_CLASS = 
129
        "org.wso2.siddhi.core.stream.output.sink.SinkMapper";
130
    
131
    /** Superclass name for Sink extensions */
132
    public static final String SINK_SUPER_CLASS = 
133
        "org.wso2.siddhi.core.stream.output.sink.Sink";
134
    
135
    /** Superclass name for Script extensions */
136
    public static final String SCRIPT_SUPER_CLASS = 
137
        "org.wso2.siddhi.core.function.Script";
138
    
139
    /** Superclass name for FunctionExecutor extensions */
140
    public static final String FUNCTION_EXECUTOR_SUPER_CLASS = 
141
        "org.wso2.siddhi.core.executor.function.FunctionExecutor";
142
    
143
    /** Superclass name for AggregationAttribute extensions */
144
    public static final String AGGREGATION_ATTRIBUTE_SUPER_CLASS = 
145
        "org.wso2.siddhi.core.query.selector.attribute.aggregator.AttributeAggregator";
146
    
147
    /** Superclass name for DistributionStrategy extensions */
148
    public static final String DISTRIBUTION_STRATEGY_SUPER_CLASS = 
149
        "org.wso2.siddhi.core.stream.output.sink.distributed.DistributionStrategy";
150
    
151
    /** Superclass name for StreamProcessor extensions */
152
    public static final String STREAM_PROCESSOR_SUPER_CLASS = 
153
        "org.wso2.siddhi.core.query.processor.stream.StreamProcessor";
154
    
155
    /** Superclass name for StreamFunctionProcessor extensions */
156
    public static final String STREAM_FUNCTION_PROCESSOR_SUPER_CLASS = 
157
        "org.wso2.siddhi.core.query.processor.stream.function.StreamFunctionProcessor";
158
    
159
    /** Superclass name for Store extensions */
160
    public static final String STORE_SUPER_CLASS = 
161
        "org.wso2.siddhi.core.table.record.AbstractRecordTable";
162
    
163
    /** Superclass name for Source extensions */
164
    public static final String SOURCE_SUPER_CLASS = 
165
        "org.wso2.siddhi.core.stream.input.source.Source";
166
    
167
    /** Superclass name for SourceMapper extensions */
168
    public static final String SOURCE_MAPPER_SUPER_CLASS = 
169
        "org.wso2.siddhi.core.stream.input.source.SourceMapper";
170
    
171
    /** Superclass name for WindowProcessor extensions */
172
    public static final String WINDOW_PROCESSOR_CLASS = 
173
        "org.wso2.siddhi.core.query.processor.stream.window.WindowProcessor";
174
    
175
    /** Superclass name for IncrementalAttributeAggregator extensions */
176
    public static final String INCREMENTAL_ATTRIBUTE_AGGREGATOR_SUPER_CLASS = 
177
        "org.wso2.siddhi.core.query.selector.attribute.aggregator.incremental.IncrementalAttributeAggregator";
178
    
179
    // Namespace Constants
180
    /** Default namespace for DistributionStrategy extensions */
181
    public static final String DISTRIBUTION_STRATEGY_NAMESPACE = "distributionStrategy";
182
    
183
    /** Default namespace for Store extensions */
184
    public static final String STORE_NAMESPACE = "store";
185
    
186
    /** Default namespace for Source extensions */
187
    public static final String SOURCE_NAMESPACE = "source";
188
    
189
    /** Default namespace for SourceMapper extensions */
190
    public static final String SOURCE_MAPPER_NAMESPACE = "sourceMapper";
191
    
192
    /** Default namespace for Sink extensions */
193
    public static final String SINK_NAMESPACE = "sink";
194
    
195
    /** Default namespace for SinkMapper extensions */
196
    public static final String SINK_MAPPER_NAMESPACE = "sinkMapper";
197
}
198
```
199

200
**Usage Examples:**
201

202
```java
203
// Extension superclass validation
204
String superClass = getMatchingSuperClass(element, new String[]{
205
    AnnotationConstants.FUNCTION_EXECUTOR_SUPER_CLASS,
206
    AnnotationConstants.STREAM_PROCESSOR_SUPER_CLASS,
207
    AnnotationConstants.SINK_SUPER_CLASS
208
});
209

210
// Namespace determination
211
if (superClass.equals(AnnotationConstants.SINK_SUPER_CLASS)) {
212
    expectedNamespace = AnnotationConstants.SINK_NAMESPACE;
213
}
214

215
// Processor selection
216
switch (superClass) {
217
    case AnnotationConstants.FUNCTION_EXECUTOR_SUPER_CLASS:
218
        processor = new FunctionExecutorValidationAnnotationProcessor(className);
219
        break;
220
    case AnnotationConstants.STREAM_PROCESSOR_SUPER_CLASS:
221
        processor = new StreamProcessorValidationAnnotationProcessor(className);
222
        break;
223
}
224
```
225

226
## Integration with External Libraries
227

228
### ClassIndex Integration
229

230
The annotations framework integrates with ClassIndex for runtime discovery of annotated extensions:
231

232
```java
233
// @Extension is marked with @IndexAnnotated
234
@IndexAnnotated
235
public @interface Extension {
236
    // Extension definition
237
}
238

239
// ClassIndex allows runtime discovery
240
Iterable<Class<?>> extensions = ClassIndex.getAnnotated(Extension.class);
241
```
242

243
**Usage in Extension Loading:**
244

245
```java
246
import org.atteo.classindex.ClassIndex;
247

248
// Discover all extension classes at runtime
249
for (Class<?> extensionClass : ClassIndex.getAnnotated(Extension.class)) {
250
    Extension annotation = extensionClass.getAnnotation(Extension.class);
251
    
252
    // Register extension with Siddhi engine
253
    registerExtension(
254
        annotation.namespace(),
255
        annotation.name(),
256
        extensionClass
257
    );
258
}
259
```
260

261
## Error Handling Patterns
262

263
### Validation Error Messages
264

265
The utility classes provide structured error messages following consistent patterns:
266

267
```java
268
// Parameter validation error
269
throw new AnnotationValidationException(MessageFormat.format(
270
    "The @Extension -> @Parameter -> name:{0} -> description annotated in class {1} is null or empty.",
271
    parameterName, extensionClassFullName
272
));
273

274
// Return attribute validation error  
275
throw new AnnotationValidationException(MessageFormat.format(
276
    "The @Extension -> @ReturnAttribute -> name {0} annotated in class {1} is not in camelCase format.",
277
    returnAttributeName, extensionClassFullName
278
));
279

280
// Basic validation error
281
throw new AnnotationValidationException(MessageFormat.format(
282
    "The @Extension -> namespace annotated in class {0} is null or empty.",
283
    extensionClassFullName
284
));
285
```
286

287
### Exception Handling During Validation
288

289
```java
290
try {
291
    abstractAnnotationProcessor.basicParameterValidation(name, description, namespace);
292
    abstractAnnotationProcessor.parameterValidation(parameters);
293
    abstractAnnotationProcessor.returnAttributesValidation(returnAttributes);
294
    abstractAnnotationProcessor.systemParametersValidation(systemParameters);
295
    abstractAnnotationProcessor.examplesValidation(examples);
296
} catch (AnnotationValidationException e) {
297
    // Convert to compilation error
298
    messager.printMessage(Diagnostic.Kind.ERROR, e.getMessage(), element);
299
}
300
```
301

302
This utility framework ensures consistent type definitions, error handling, and extension classification throughout the Siddhi annotations system.