Annotations

Complete reference for all Talon annotations available for microservice development.

Overview

Talon provides a comprehensive set of Java annotations for developing microservices. These annotations enable declarative configuration of:

Microservice lifecycle hooks
Message and event handlers
Configuration injection
Command handlers
Application statistics
Store indexes

Annotation Categories

Lifecycle

Control microservice lifecycle and dependency injection

Message Processing

Handle inbound messages and events

Configuration

Inject configuration values

Command & Control

Implement administrative commands

Monitoring

Expose application statistics

Storage

Configure state storage and indexing

Container Accessor

Expose objects for annotation scanning

Lifecycle Annotations

@AppHAPolicy

Package: com.neeve.server.app.annotations Target: TYPE (class level) Since: 1.0

Specifies the high-availability policy for the microservice.

Parameters:

value (required): HAPolicy enum - EventSourcing or StateReplication

Example:

@AppHAPolicy(HAPolicy.EventSourcing)
public class MyApp {
    // ...
}

@AppInjectionPoint

Package: com.neeve.server.app.annotations Target: METHOD, FIELD Since: 1.0

Marks methods or fields for dependency injection by the Talon runtime.

Supported Injectable Types:

SrvAppLoader - Application loader
AepEngine - AEP engine instance
AepEngineDescriptor - Engine configuration descriptor
AepMessageSender - Message sender

Examples:

// Field injection
@AppInjectionPoint
private AepMessageSender sender;

// Method injection
@AppInjectionPoint
public void setEngine(AepEngine engine) {
    this.engine = engine;
}

See Also: Lifecycle

@AppInitializer

Package: com.neeve.server.app.annotations Target: METHOD Since: 1.0

Marks the application initialization method, invoked after the engine is created and injected.

Example:

@AppInitializer
public void initialize() {
    // Initialization logic
}

@AppMain

Package: com.neeve.server.app.annotations Target: METHOD Since: 1.0

Marks the main entry point for synchronous microservices. Invoked in a separate thread after the engine becomes primary.

Example:

@AppMain
public void main() {
    // Main logic for sender-only applications
}

See Also: Lifecycle

@AppFinalizer

Package: com.neeve.server.app.annotations Target: METHOD Since: 1.0

Marks the application finalization method, invoked during shutdown before the application is unloaded.

Example:

@AppFinalizer
public void finalize() {
    // Cleanup logic
}

See Also: Lifecycle

Message Processing Annotations

@EventHandler

Package: com.neeve.aep.annotations Target: METHOD Since: 1.0

Marks methods as handlers for inbound messages or lifecycle events.

Parameters:

source (optional, default: "*"): Source filter for events
localOnly (optional, default: false): Handle only locally-sourced events (experimental)

Valid Method Signatures:

// Message handler
@EventHandler
void onMessage(MessageView message) { }

// Message handler with state (State Replication only)
@EventHandler
void onMessage(MessageView message, IStoreObject state) { }

// Event handler
@EventHandler
void onEvent(IEvent event) { }

Example:

@EventHandler
public void onOrder(NewOrderMessage message) {
    // Process order
}

@EventHandler
public void onEngineActive(AepEngineActiveEvent event) {
    // Handle engine activation
}

See Also: Handling Messages, Lifecycle Events

Configuration Annotations

@Configured

Package: com.neeve.cli.annotations Target: FIELD, METHOD Since: 3.2

Marks fields or methods for configuration injection from XRuntime.

Parameters:

property (required): Configuration property name
required (optional, default: false): Whether property is required
defaultValue (optional, default: ""): Default value if property not set
description (optional, default: ""): Property description

Supported Types: boolean, byte, short, int, long, float, double, char, String, XString, enumerations

Examples:

// Field injection
@Configured(property = "myapp.maxSize", defaultValue = "1000")
private int maxSize;

// Method injection
@Configured(property = "myapp.enabled", required = true)
void setEnabled(boolean enabled) {
    this.enabled = enabled;
}

See Also: Injecting Configuration

Command & Control Annotations

@Command

Package: com.neeve.cli.annotations Target: TYPE, METHOD Since: 3.4

Marks a method as an executable command handler for administrative operations.

Parameters:

name (optional): Command name (defaults to method name)
description (optional): Command description
aliases (optional): Alternative command names
parseOptions (optional, default: true): Whether to parse options

Example:

@Command(name = "resetStats", description = "Reset order statistics")
public String resetStats(@Option(shortForm = 'v', longForm = "verbose") boolean verbose) {
    // Reset logic
    return "Stats reset";
}

See Also: Implementing Command Handlers

@Argument

Package: com.neeve.cli.annotations Target: FIELD, PARAMETER Since: 3.4

Defines a positional command argument.

Parameters:

name (required): Argument name
position (required): 1-based position
description (optional): Argument description
defaultValue (optional): Default value
required (optional, default: true): Whether argument is required
validOptions (optional): Array of valid values

Example:

@Command
public String processOrder(
    @Argument(name = "orderId", position = 1) long orderId,
    @Argument(name = "quantity", position = 2, defaultValue = "1") int quantity) {
    // Process order
}

See Also: Implementing Command Handlers

@Option

Package: com.neeve.cli.annotations Target: FIELD, PARAMETER Since: 3.4

Defines a command option (switch-based parameter).

Parameters:

shortForm (required): Short switch character (e.g., 'v')
longForm (required): Long switch name (e.g., "verbose")
description (optional): Option description
defaultValue (optional): Default value
required (optional, default: false): Whether option is required
validOptions (optional): Array of valid values

Example:

@Command
public String process(
    @Option(shortForm = 'v', longForm = "verbose", defaultValue = "false")
    boolean verbose) {
    // Process with optional verbosity
}

See Also: Implementing Command Handlers

@AppCommandHandler

Package: com.neeve.server.app.annotations Target: METHOD Since: 1.0

Legacy annotation for marking command handlers. @Command is now preferred.

Parameters:

command (required): Command name

Example:

@AppCommandHandler(command = "printhelloworld")
public String helloWorld(String command, String[] args) {
    System.out.println("Hello World!");
    return "Done";
}

See Also: Implementing Command Handlers

Monitoring Annotations

@AppStat

Package: com.neeve.server.app.annotations Target: METHOD, FIELD Since: 1.0

Marks fields or methods that provide statistic values for collection by the engine's statistics collector.

Parameters:

gauge (optional, default: true): Whether field/method is a gauge
name (optional): Name of the gauge (for gauge stats)

Supported Types:

IStats.Counter - Counter statistics
IStats.Latencies - Latency statistics
IStats.Gauge - Gauge statistics
Primitive types (when gauge=true)

Examples:

// Counter stat
@AppStat(gauge = false)
private final Counter ordersProcessed = StatsFactory.createCounterStat();

// Gauge stat from field
@AppStat(name = "Queue Size")
private volatile int queueSize = 0;

// Gauge stat from method
@AppStat(name = "Active Orders")
public int getActiveOrders() {
    return activeOrders.size();
}

See Also: Exposing Application Stats

Storage Annotations

@AppStateFactoryAccessor

Package: com.neeve.server.app.annotations Target: METHOD Since: 1.0

Provides the state factory for State Replication microservices.

Return Type: IAepApplicationStateFactory

Example:

@AppStateFactoryAccessor
public IAepApplicationStateFactory getStateFactory() {
    return new IAepApplicationStateFactory() {
        @Override
        public Repository createState(MessageView view) {
            return Repository.create();
        }
    };
}

See Also: State Replication Template

@AppStoreUniqueIndex

Package: com.neeve.server.app.annotations Target: FIELD (type: IStoreUniqueIndex) Since: 2.0

Defines a unique index on state objects for State Replication microservices.

Parameters:

name (required): Index name
fieldPath (required): Field path on which to create index

Example:

@AppStoreUniqueIndex(name = "customerIdIndex", fieldPath = "customerId")
private IStoreUniqueIndex<Long, Customer> customerIndex;

@AppStoreNonUniqueIndex

Package: com.neeve.server.app.annotations Target: FIELD (type: IStoreNonUniqueIndex) Since: 2.0

Defines a non-unique index on state objects for State Replication microservices.

Parameters:

name (required): Index name
fieldPath (required): Field path on which to create index

Example:

@AppStoreNonUniqueIndex(name = "cityIndex", fieldPath = "address.city")
private IStoreNonUniqueIndex<String, Customer> cityIndex;

Container Accessor Annotations

These annotations expose objects to the Talon runtime for annotation scanning.

@AppIntrospectionPoints

Package: com.neeve.server.app.annotations Target: METHOD Since: 3.0

Unified accessor that exposes objects for all annotation types. Called multiple times during lifecycle.

Method Signature:

@AppIntrospectionPoints
public void getIntrospectionPoints(Set<Object> objects) {
    objects.add(myHandler);
}

Replaces: All fine-grained *Accessor annotations

See Also: Lifecycle

@AppConfiguredAccessor

Package: com.neeve.server.app.annotations Target: METHOD Since: 3.2

Exposes objects containing @Configured annotations.

Method Signature:

@AppConfiguredAccessor
public void getConfiguredObjects(Set<Object> objects) {
    objects.add(myConfiguredObject);
}

See Also: Injecting Configuration

@AppCommandHandlerContainersAccessor

Package: com.neeve.server.app.annotations Target: METHOD Since: 3.4

Exposes objects containing @Command methods.

Method Signature:

@AppCommandHandlerContainersAccessor
public void getCommandHandlers(Set<Object> containers) {
    containers.add(myCommandHandler);
}

See Also: Implementing Command Handlers

@AppEventHandlerContainersAccessor

Package: com.neeve.server.app.annotations Target: METHOD Since: 1.0

Exposes objects containing @EventHandler methods.

Method Signature:

@AppEventHandlerContainersAccessor
public void getEventHandlers(Set<Object> containers) {
    containers.add(myEventHandler);
}

See Also: Handling Messages

@AppEventHandlerAccessor

Package: com.neeve.server.app.annotations Target: METHOD Since: 1.0

Provides the default event handler (programmatic alternative to @EventHandler).

Return Type: IEventHandler

Method Signature:

@AppEventHandlerAccessor
public IEventHandler getDefaultEventHandler() {
    return myEventHandler;
}

See Also: Lifecycle

@AppStatContainersAccessor

Package: com.neeve.server.app.annotations Target: METHOD Since: 1.0

Exposes objects containing @AppStat annotations.

Method Signature:

@AppStatContainersAccessor
public void getStatContainers(Set<Object> containers) {
    containers.add(myStatsProvider);
}

See Also: Exposing Application Stats

Annotation Packages

Talon annotations are organized into three packages:

com.neeve.aep.annotations

AEP Engine-level annotations:

@EventHandler

com.neeve.server.app.annotations

Talon application-level annotations (16 annotations):

All @App* annotations
Lifecycle, injection, and accessor annotations

com.neeve.cli.annotations

Configuration and command-line interface annotations (4 annotations):

@Configured
@Command
@Argument
@Option

Import Examples

// Lifecycle annotations
import com.neeve.server.app.annotations.AppHAPolicy;
import com.neeve.server.app.annotations.AppInjectionPoint;
import com.neeve.server.app.annotations.AppInitializer;

// Message processing
import com.neeve.aep.annotations.EventHandler;

// Configuration
import com.neeve.cli.annotations.Configured;

// Commands
import com.neeve.cli.annotations.Command;
import com.neeve.cli.annotations.Argument;
import com.neeve.cli.annotations.Option;

// Monitoring
import com.neeve.server.app.annotations.AppStat;

Lifecycle Execution Order

Annotations are processed in this order during microservice startup:

@AppInjectionPoint (SrvAppLoader)
@AppHAPolicy
@AppInjectionPoint (AepEngineDescriptor)
@AppConfiguredAccessor / @Configured
@AppCommandHandlerContainersAccessor / @Command
@AppStatContainersAccessor / @AppStat
@AppEventHandlerContainersAccessor / @EventHandler
@AppEventHandlerAccessor
@AppStateFactoryAccessor
@AppInjectionPoint (AepEngine)
@AppInitializer
@AppMain (after becoming primary)
@AppFinalizer (during shutdown)

See Lifecycle for complete flow.