tessl/maven-org-wso2-siddhi--siddhi-annotations

Annotation support for the Siddhi Complex Event Processing Engine, providing extension definitions and validation for stream processors, functions, aggregations, and other extension types.

Overview

Eval results

Files

Core Annotations

Name: tessl/maven-org-wso2-siddhi--siddhi-annotations
Author: tessl

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.

Capabilities

@Extension Annotation

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

/**
 * Annotation for specifying it as a Siddhi Extension.
 * Must be applied to classes that extend Siddhi extension superclasses.
 * 
 * @Target ElementType.TYPE
 * @Retention RetentionPolicy.RUNTIME
 * @IndexAnnotated
 */
@interface Extension {
    /** Extension name - required for non-core extensions */
    String name() default "";
    
    /** Extension namespace - required for non-core extensions */
    String namespace() default "";
    
    /** Description of the extension functionality - required */
    String description() default "";
    
    /** Array of parameter definitions */
    Parameter[] parameters() default {};
    
    /** Array of system parameter definitions */
    SystemParameter[] systemParameter() default {};
    
    /** Array of return attribute definitions */
    ReturnAttribute[] returnAttributes() default {};
    
    /** Array of usage examples */
    Example[] examples() default {};
}

Usage Example:

import org.wso2.siddhi.annotation.util.DataType;

@Extension(
    name = "customFunction",
    namespace = "custom",
    description = "Performs custom data processing on input values.",
    parameters = {
        @Parameter(name = "input", 
                  type = {DataType.STRING}, 
                  description = "Input string to process"),
        @Parameter(name = "mode", 
                  type = {DataType.STRING}, 
                  description = "Processing mode",
                  optional = true,
                  defaultValue = "default")
    },
    returnAttributes = @ReturnAttribute(
        type = {DataType.STRING}, 
        description = "Processed output string"
    ),
    examples = @Example(
        syntax = "from inputStream#custom:customFunction(data, 'advanced') select result insert into outputStream;",
        description = "Process input data using advanced mode."
    )
)
public class CustomFunction extends FunctionExecutor {
    // Implementation
}

@Parameter Annotation

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

/**
 * Annotation for storing the parameters of a Siddhi Extension.
 * Used within @Extension parameter arrays.
 * 
 * @Retention RetentionPolicy.RUNTIME
 * @Target {} - No direct target, used within @Extension
 */
@interface Parameter {
    /** Parameter name in dot notation format (e.g., "param.subparam") */
    String name() default "";
    
    /** Array of supported data types for this parameter */
    DataType[] type() default {};
    
    /** Description of the parameter's purpose and usage */
    String description() default "";
    
    /** Whether this parameter is optional (default: false) */
    boolean optional() default false;
    
    /** Whether this parameter supports dynamic values (Sink/SinkMapper only) */
    boolean dynamic() default false;
    
    /** Default value for optional parameters */
    String defaultValue() default "";
}

Usage Examples:

// Required parameter
@Parameter(name = "host", 
          type = {DataType.STRING}, 
          description = "Server hostname")

// Optional parameter with default
@Parameter(name = "port", 
          type = {DataType.INT}, 
          description = "Server port number",
          optional = true,
          defaultValue = "8080")

// Dynamic parameter (Sink/SinkMapper only)
@Parameter(name = "headers", 
          type = {DataType.STRING}, 
          description = "HTTP headers",
          dynamic = true)

@ReturnAttribute Annotation

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

/**
 * Annotation for storing additional attributes returned by a stream processor.
 * Used within @Extension returnAttributes arrays.
 * 
 * @Retention RetentionPolicy.RUNTIME
 * @Target {} - No direct target, used within @Extension
 */
@interface ReturnAttribute {
    /** Name of the return attribute (camelCase format) */
    String name() default "";
    
    /** Array of possible data types for this attribute */
    DataType[] type() default {};
    
    /** Description of the attribute's meaning and usage */
    String description() default "";
}

Usage Examples:

// Single return attribute
@ReturnAttribute(name = "average", 
                type = {DataType.DOUBLE}, 
                description = "Calculated average value")

// Multiple return attributes
returnAttributes = {
    @ReturnAttribute(name = "sum", 
                    type = {DataType.LONG, DataType.DOUBLE}, 
                    description = "Sum of all values"),
    @ReturnAttribute(name = "count", 
                    type = {DataType.LONG}, 
                    description = "Number of values processed")
}

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

@SystemParameter Annotation

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

/**
 * Annotation for storing the system parameters of a Siddhi Extension.
 * Used within @Extension systemParameter arrays.
 * 
 * @Retention RetentionPolicy.RUNTIME
 * @Target {} - No direct target, used within @Extension
 */
@interface SystemParameter {
    /** System parameter name */
    String name() default "";
    
    /** Description of the system parameter's purpose */
    String description() default "";
    
    /** Default value for the system parameter */
    String defaultValue() default "";
    
    /** Array of possible values for this parameter */
    String[] possibleParameters() default {};
}

Usage Example:

@SystemParameter(
    name = "threading.mode",
    description = "Threading mode for parallel processing",
    defaultValue = "single",
    possibleParameters = {"single", "multi", "adaptive"}
)

@Example Annotation

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

/**
 * Optional annotation for storing examples for a Siddhi Extension.
 * Used within @Extension examples arrays.
 * 
 * @Retention RetentionPolicy.RUNTIME
 * @Target {} - No direct target, used within @Extension
 */
@interface Example {
    /** Example syntax showing how to use the extension */
    String syntax() default "";
    
    /** Description explaining what the example demonstrates */
    String description() default "";
}

Usage Examples:

// Single example
@Example(
    syntax = "from streamA#window.time(10 sec) select * insert into streamB;",
    description = "Process events within a 10-second time window."
)

// Multiple examples
examples = {
    @Example(
        syntax = "from dataStream#custom:transform('upper') select result insert into output;",
        description = "Transform text to uppercase."
    ),
    @Example(
        syntax = "from dataStream#custom:transform('lower') select result insert into output;",
        description = "Transform text to lowercase."
    )
}

Validation Rules

All core annotations are subject to compile-time validation:

@Extension Validation

name cannot be empty for non-core extensions
description cannot be empty
namespace cannot be empty for non-core extensions
Must have at least one @Example
Class must extend a valid Siddhi extension superclass

@Parameter Validation

name cannot be empty and must follow dot notation pattern: ^[a-z][a-z0-9]*(\\.[a-z][a-z0-9]*)*$
description cannot be empty
type array cannot be empty
If optional is true, defaultValue cannot be empty
dynamic can only be true for Sink and SinkMapper extensions

@ReturnAttribute Validation

name must follow camelCase pattern: ^(([a-z][a-z0-9]+)([A-Z]{0,1}[a-z0-9]*)*)$
description cannot be empty
type array cannot be empty
Function executors can have only one return attribute with empty name

@SystemParameter Validation

name cannot be empty
description cannot be empty
defaultValue cannot be empty
possibleParameters array cannot be empty

@Example Validation

syntax cannot be empty
description cannot be empty
At least one example is required per extension

Install with Tessl CLI

npx tessl i tessl/maven-org-wso2-siddhi--siddhi-annotations

docs

annotation-processors.md

tessl/maven-org-wso2-siddhi--siddhi-annotations