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

# Annotations

Complete reference for all Rumi annotations available for microservice development.

## Overview

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

Control microservice lifecycle and dependency injection

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

Handle inbound messages and events

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

Inject configuration values

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

Implement administrative commands

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

Expose application statistics

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

Configure state storage and indexing

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

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](/rumi-core/concepts/consensus-models.md), [Specifying The HA Policy](/rumi-core/guides/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 Rumi 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](/rumi-core/concepts/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](/rumi-core/concepts/microservice-operation/lifecycle.md#initialize-application), [Implementing Lifecycle Methods](/rumi-core/guides/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](/rumi-core/concepts/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](/rumi-core/concepts/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](/rumi-core/guides/developing-applications/authoring-user-code/message-processing/processing-messages/handling-messages.md), [Lifecycle Events](/rumi-core/reference/events.md)

***

## Configuration Annotations

### @Configured

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

Marks fields or methods for configuration injection from the global environment.

**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](/rumi-core/guides/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](/rumi-core/guides/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](/rumi-core/guides/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](/rumi-core/guides/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](/rumi-core/guides/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](/rumi-core/guides/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](/rumi-core/guides/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 Rumi 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](/rumi-core/concepts/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](/rumi-core/guides/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](/rumi-core/guides/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](/rumi-core/guides/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](/rumi-core/concepts/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](/rumi-core/guides/developing-applications/authoring-user-code/monitoring/exposing-application-statistics.md)

***

## Annotation Packages

Rumi annotations are organized into three packages:

### com.neeve.aep.annotations

AEP Engine-level annotations:

* @EventHandler

### com.neeve.server.app.annotations

Rumi 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](/rumi-core/concepts/microservice-operation/lifecycle.md) for complete flow.

***

## See Also

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.rumi.systems/rumi-core/reference/annotations.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.