> For the complete documentation index, see [llms.txt](https://docs.xplatform.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xplatform.com/talon/reference/annotations.md).

# 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](#lifecycle-annotations)

Control microservice lifecycle and dependency injection

### [Message Processing](#message-processing-annotations)

Handle inbound messages and events

### [Configuration](#configuration-annotations)

Inject configuration values

### [Command & Control](#command-control-annotations)

Implement administrative commands

### [Monitoring](#monitoring-annotations)

Expose application statistics

### [Storage](#storage-annotations)

Configure state storage and indexing

### [Container Accessor](#container-accessor-annotations)

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**:

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

**See Also**: [Consensus Models](/talon/concepts-and-architecture/consensus-models.md), [Specifying The HA Policy](/talon/developing-applications/authoring-user-code/consensus-model/specifying-the-ha-policy.md)

***

### @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**:

```java
// Field injection
@AppInjectionPoint
private AepMessageSender sender;

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

**See Also**: [Lifecycle](/talon/concepts-and-architecture/microservice-operation/lifecycle.md#inject-engine)

***

### @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**:

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

**See Also**: [Lifecycle](/talon/concepts-and-architecture/microservice-operation/lifecycle.md#initialize-application), [Implementing Lifecycle Methods](/talon/developing-applications/authoring-user-code/lifecycle/implementing-lifecycle-methods.md)

***

### @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**:

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

**See Also**: [Lifecycle](/talon/concepts-and-architecture/microservice-operation/lifecycle.md#synchronous-applications)

***

### @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**:

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

**See Also**: [Lifecycle](/talon/concepts-and-architecture/microservice-operation/lifecycle.md#finalize-application)

***

## 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**:

```java
// 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**:

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

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

**See Also**: [Handling Messages](/talon/developing-applications/authoring-user-code/message-processing/processing-messages/handling-messages.md), [Lifecycle Events](/talon/reference/events.md#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**:

```java
// 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](/talon/developing-applications/authoring-user-code/configuration/injecting-configuration.md)

***

## 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**:

```java
@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](/talon/developing-applications/authoring-user-code/command-and-control/implementing-command-handlers.md)

***

### @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**:

```java
@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](/talon/developing-applications/authoring-user-code/command-and-control/implementing-command-handlers.md)

***

### @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**:

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

**See Also**: [Implementing Command Handlers](/talon/developing-applications/authoring-user-code/command-and-control/implementing-command-handlers.md)

***

### @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**:

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

**See Also**: [Implementing Command Handlers](/talon/developing-applications/authoring-user-code/command-and-control/implementing-command-handlers.md)

***

## 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**:

```java
// 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](/talon/developing-applications/authoring-user-code/monitoring/exposing-application-statistics.md)

***

## 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**:

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

**See Also**: [State Replication Template](/talon/developing-applications/microservice-template/state-replication-template.md)

***

### @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**:

```java
@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**:

```java
@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**:

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

**Replaces**: All fine-grained \*Accessor annotations

**See Also**: [Lifecycle](/talon/concepts-and-architecture/microservice-operation/lifecycle.md)

***

### @AppConfiguredAccessor

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

Exposes objects containing @Configured annotations.

**Method Signature**:

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

**See Also**: [Injecting Configuration](/talon/developing-applications/authoring-user-code/configuration/injecting-configuration.md)

***

### @AppCommandHandlerContainersAccessor

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

Exposes objects containing @Command methods.

**Method Signature**:

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

**See Also**: [Implementing Command Handlers](/talon/developing-applications/authoring-user-code/command-and-control/implementing-command-handlers.md)

***

### @AppEventHandlerContainersAccessor

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

Exposes objects containing @EventHandler methods.

**Method Signature**:

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

**See Also**: [Handling Messages](/talon/developing-applications/authoring-user-code/message-processing/processing-messages/handling-messages.md)

***

### @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**:

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

**See Also**: [Lifecycle](/talon/concepts-and-architecture/microservice-operation/lifecycle.md#get-default-event-handler)

***

### @AppStatContainersAccessor

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

Exposes objects containing @AppStat annotations.

**Method Signature**:

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

**See Also**: [Exposing Application Stats](/talon/developing-applications/authoring-user-code/monitoring/exposing-application-statistics.md)

***

## 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

```java
// 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:

1. `@AppInjectionPoint` (SrvAppLoader)
2. `@AppHAPolicy`
3. `@AppInjectionPoint` (AepEngineDescriptor)
4. `@AppConfiguredAccessor` / `@Configured`
5. `@AppCommandHandlerContainersAccessor` / `@Command`
6. `@AppStatContainersAccessor` / `@AppStat`
7. `@AppEventHandlerContainersAccessor` / `@EventHandler`
8. `@AppEventHandlerAccessor`
9. `@AppStateFactoryAccessor`
10. `@AppInjectionPoint` (AepEngine)
11. `@AppInitializer`
12. `@AppMain` (after becoming primary)
13. `@AppFinalizer` (during shutdown)

See [Lifecycle](/talon/concepts-and-architecture/microservice-operation/lifecycle.md) for complete flow.

***

## See Also

* [Lifecycle](/talon/concepts-and-architecture/microservice-operation/lifecycle.md) - Microservice lifecycle and annotation processing
* [Events](/talon/reference/events.md) - Lifecycle and runtime events
* [Implementing Lifecycle Methods](/talon/developing-applications/authoring-user-code/lifecycle/implementing-lifecycle-methods.md) - Using lifecycle annotations
* [Handling Messages](/talon/developing-applications/authoring-user-code/message-processing/processing-messages/handling-messages.md) - Using @EventHandler
* [Injecting Configuration](/talon/developing-applications/authoring-user-code/configuration/injecting-configuration.md) - Using @Configured
* [Implementing Command Handlers](/talon/developing-applications/authoring-user-code/command-and-control/implementing-command-handlers.md) - Using command annotations
* [Exposing Application Stats](/talon/developing-applications/authoring-user-code/monitoring/exposing-application-statistics.md) - Using @AppStat