> 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/events.md).

# Events

Complete reference for all lifecycle and runtime events dispatched by the Rumi runtime that can be processed by microservices.

## Overview

Rumi dispatches events during the microservice lifecycle and runtime operation. Microservices can handle these events by implementing @EventHandler annotated methods.

Events provide hooks to:

* Monitor lifecycle state transitions
* React to messaging connectivity changes
* Track store and cluster membership changes
* Implement custom logic at specific operational points

## Event Types

Rumi events fall into two categories based on their notification semantics:

### Lifecycle Events

**Interface**: `ILifecycleEvent`

Lifecycle events notify the microservice of normal state transitions in the engine, messaging, or store lifecycle. These events represent expected operational flows and milestones, such as engine startup, channel connections, and cluster membership changes.

**Examples**: AepEngineCreatedEvent, AepChannelUpEvent, IStoreMemberUpEvent

### Alert Events

**Interface**: `IAlertEvent`

Alert events notify the microservice of exceptional conditions, failures, or problems that require attention. Alert events always implement both IAlertEvent and ILifecycleEvent, indicating they are lifecycle events with alert semantics.

**Examples**: AepMessagingFailedEvent, AepBusBindingDownEvent, IStoreBindingFailedEvent

**See Also**: [Development Model - Notification Methods](/rumi-core/concepts/microservice-architecture/development-model.md#lifecycle-methods)

## Event Categories

Events are organized by their source component:

### [Engine Events](#engine-events)

Core engine lifecycle events

### [Messaging Events](#messaging-events)

Message bus and channel connectivity events

### [Store Events](#store-events)

Store binding and cluster membership events

***

## Engine Events

### AepEngineCreatedEvent

**Package**: `com.neeve.aep.event` **Event Type**: Lifecycle **Dispatched**: When the AEP engine has been successfully created

**Description**: Dispatched after the engine is instantiated but before it is started. At this point, the engine configuration is finalized and messaging connections are prepared but not yet established.

**Handler Example**:

```java
@EventHandler
public void onEngineCreated(AepEngineCreatedEvent event) {
    logger.info("Engine created");
}
```

**Javadoc**: [AepEngineCreatedEvent](https://build.neeveresearch.com/rumi/javadoc/LATEST/com/neeve/aep/event/AepEngineCreatedEvent.html)

**See Also**: [Lifecycle - Create Engine](/rumi-core/concepts/microservice-operation/lifecycle.md#create-engine)

***

### AepMessagingPrestartEvent

**Package**: `com.neeve.aep.event` **Event Type**: Lifecycle **Dispatched**: Before the engine attempts to establish message bus bindings

**Description**: Dispatched before the engine starts its messaging machinery. This event precedes any connection attempts to message buses or channels.

**Handler Example**:

```java
@EventHandler
public void onMessagingPrestart(AepMessagingPrestartEvent event) {
    logger.info("Messaging about to start");
}
```

**Javadoc**: [AepMessagingPrestartEvent](https://build.neeveresearch.com/rumi/javadoc/LATEST/com/neeve/aep/event/AepMessagingPrestartEvent.html)

**See Also**: [Lifecycle - Activate Engine](/rumi-core/concepts/microservice-operation/lifecycle.md#activate-engine)

***

### AepMessagingStartedEvent

**Package**: `com.neeve.aep.event` **Event Type**: Lifecycle **Dispatched**: After the engine has attempted to establish message bus bindings

**Description**: Dispatched after the engine completes messaging startup, whether successful or not. This event is dispatched after corresponding channel up events for successfully established bindings.

**Handler Example**:

```java
@EventHandler
public void onMessagingStarted(AepMessagingStartedEvent event) {
    logger.info("Messaging started");
}
```

**Javadoc**: [AepMessagingStartedEvent](https://build.neeveresearch.com/rumi/javadoc/LATEST/com/neeve/aep/event/AepMessagingStartedEvent.html)

**See Also**: [Lifecycle - Activate Engine](/rumi-core/concepts/microservice-operation/lifecycle.md#activate-engine)

***

### AepMessagingStartFailedEvent

**Package**: `com.neeve.aep.event` **Event Type**: Alert **Dispatched**: When the engine fails to start its messaging machinery

**Description**: Dispatched when the engine encounters a failure during messaging startup. For bindings that were successfully established before the failure, corresponding binding and channel up events would have been dispatched before this event.

**Handler Example**:

```java
@EventHandler
public void onMessagingStartFailed(AepMessagingStartFailedEvent event) {
    logger.error("Messaging start failed: {}", event.getCause());
}
```

**Javadoc**: [AepMessagingStartFailedEvent](https://build.neeveresearch.com/rumi/javadoc/LATEST/com/neeve/aep/event/AepMessagingStartFailedEvent.html)

***

### AepEngineStartedEvent

**Package**: `com.neeve.aep.event` **Event Type**: Lifecycle **Dispatched**: When the AEP engine has been successfully started

**Description**: Dispatched after the engine completes startup and determines its role (primary or backup) in the cluster. The engine is running but may not yet be processing messages if it's a backup.

**Handler Example**:

```java
@EventHandler
public void onEngineStarted(AepEngineStartedEvent event) {
    logger.info("Engine started as {}", event.getEngine().isPrimary() ? "primary" : "backup");
}
```

**Javadoc**: [AepEngineStartedEvent](https://build.neeveresearch.com/rumi/javadoc/LATEST/com/neeve/aep/event/AepEngineStartedEvent.html)

**See Also**: [Lifecycle - Start Engine](/rumi-core/concepts/microservice-operation/lifecycle.md#start-engine)

***

### AepEngineActiveEvent

**Package**: `com.neeve.aep.event` **Event Type**: Lifecycle **Dispatched**: When the engine has been elected as primary and successfully started messaging

**Description**: Dispatched when the engine becomes the active primary instance in the cluster. This event indicates the engine is fully operational and processing messages. Corresponding binding and channel up events are dispatched before this event.

**Handler Example**:

```java
@EventHandler
public void onEngineActive(AepEngineActiveEvent event) {
    logger.info("Engine is now primary and active");
    // Safe to start background processing, scheduled tasks, etc.
}
```

**Javadoc**: [AepEngineActiveEvent](https://build.neeveresearch.com/rumi/javadoc/LATEST/com/neeve/aep/event/AepEngineActiveEvent.html)

**See Also**: [Lifecycle - Activate Engine](/rumi-core/concepts/microservice-operation/lifecycle.md#activate-engine)

***

### AepFlowCreatedEvent

**Package**: `com.neeve.aep.event` **Event Type**: Lifecycle **Dispatched**: When the AEP engine creates a new AepFlow

**Description**: Dispatched when a message is processed for a flow that doesn't yet exist. AepFlows are created either during steady state on a primary or backup instance, or during recovery.

**Handler Example**:

```java
@EventHandler
public void onFlowCreated(AepFlowCreatedEvent event) {
    logger.debug("New flow created: {}", event.getFlow().getId());
}
```

**Javadoc**: [AepFlowCreatedEvent](https://build.neeveresearch.com/rumi/javadoc/LATEST/com/neeve/aep/event/AepFlowCreatedEvent.html)

***

### AepStateCreatedEvent

**Package**: `com.neeve.aep.event` **Event Type**: Lifecycle **Dispatched**: When an instance of microservice store has been created

**Description**: Dispatched only on backup AEP engine instances when the service store is created during replication from the primary. This event indicates a new store object has been instantiated and initialized from the primary's replication stream.

**Handler Example**:

```java
@EventHandler
public void onStateCreated(AepStateCreatedEvent event) {
    logger.debug("State created on backup");
}
```

**Javadoc**: [AepStateCreatedEvent](https://build.neeveresearch.com/rumi/javadoc/LATEST/com/neeve/aep/event/AepStateCreatedEvent.html)

***

### AepMessagingFailedEvent

**Package**: `com.neeve.aep.event` **Event Type**: Alert **Dispatched**: When the engine shuts down messaging due to a failure

**Description**: Dispatched when the engine has shut down all established message bus bindings due to a messaging failure. Whether and how an engine decides to shut down messaging is determined by the MessageBusBindingFailPolicy configuration.

**Handler Example**:

```java
@EventHandler
public void onMessagingFailed(AepMessagingFailedEvent event) {
    logger.error("Messaging failed: {}", event.getCause());
}
```

**Javadoc**: [AepMessagingFailedEvent](https://build.neeveresearch.com/rumi/javadoc/LATEST/com/neeve/aep/event/AepMessagingFailedEvent.html)

**See Also**: [MessageBusBindingFailPolicy](https://build.neeveresearch.com/rumi/javadoc/LATEST/com/neeve/aep/AepEngine.MessageBusBindingFailPolicy.html)

***

### AepEngineStoppedEvent

**Package**: `com.neeve.aep.event` **Event Type**: Lifecycle **Dispatched**: When the AEP engine has been stopped

**Description**: Dispatched when the engine completes shutdown. All messaging connections have been closed and resources have been cleaned up.

**Handler Example**:

```java
@EventHandler
public void onEngineStopped(AepEngineStoppedEvent event) {
    logger.info("Engine stopped");
}
```

**Javadoc**: [AepEngineStoppedEvent](https://build.neeveresearch.com/rumi/javadoc/LATEST/com/neeve/aep/event/AepEngineStoppedEvent.html)

**See Also**: [Lifecycle - Stop Engine](/rumi-core/concepts/microservice-operation/lifecycle.md#stop-engine)

***

## Messaging Events

### AepBusBindingCreatedEvent

**Package**: `com.neeve.aep.event` **Event Type**: Lifecycle **Dispatched**: When the engine creates a binding to a message bus

**Description**: Dispatched when a bus binding is instantiated but before it is opened or started. This is the first event in the bus binding lifecycle.

**Handler Example**:

```java
@EventHandler
public void onBindingCreated(AepBusBindingCreatedEvent event) {
    logger.info("Bus binding created: {}", event.getBinding().getName());
}
```

**Javadoc**: [AepBusBindingCreatedEvent](https://build.neeveresearch.com/rumi/javadoc/LATEST/com/neeve/aep/event/AepBusBindingCreatedEvent.html)

***

### AepBusBindingCreateFailedEvent

**Package**: `com.neeve.aep.event` **Event Type**: Alert **Dispatched**: When the engine encounters a failure creating a bus binding

**Description**: Dispatched when the engine fails to instantiate a bus binding, typically due to configuration errors or missing dependencies.

**Handler Example**:

```java
@EventHandler
public void onBindingCreateFailed(AepBusBindingCreateFailedEvent event) {
    logger.error("Failed to create binding: {}", event.getCause());
}
```

**Javadoc**: [AepBusBindingCreateFailedEvent](https://build.neeveresearch.com/rumi/javadoc/LATEST/com/neeve/aep/event/AepBusBindingCreateFailedEvent.html)

***

### AepBusBindingOpeningEvent

**Package**: `com.neeve.aep.event` **Event Type**: Lifecycle **Dispatched**: Just before the engine starts opening a binding

**Description**: Dispatched immediately before the engine attempts to open a bus binding. This event is followed by either a binding open or binding open fail event.

**Handler Example**:

```java
@EventHandler
public void onBindingOpening(AepBusBindingOpeningEvent event) {
    logger.info("Opening binding: {}", event.getBinding().getName());
}
```

**Javadoc**: [AepBusBindingOpeningEvent](https://build.neeveresearch.com/rumi/javadoc/LATEST/com/neeve/aep/event/AepBusBindingOpeningEvent.html)

***

### AepBusBindingOpenedEvent

**Package**: `com.neeve.aep.event` **Event Type**: Lifecycle **Dispatched**: When the engine has successfully opened a bus binding

**Description**: Dispatched when a bus binding successfully establishes its underlying connection to the message bus provider.

**Handler Example**:

```java
@EventHandler
public void onBindingOpened(AepBusBindingOpenedEvent event) {
    logger.info("Binding opened: {}", event.getBinding().getName());
}
```

**Javadoc**: [AepBusBindingOpenedEvent](https://build.neeveresearch.com/rumi/javadoc/LATEST/com/neeve/aep/event/AepBusBindingOpenedEvent.html)

***

### AepBusBindingOpenFailedEvent

**Package**: `com.neeve.aep.event` **Event Type**: Alert **Dispatched**: When the engine encounters a failure opening a bus binding

**Description**: Dispatched when the engine fails to open a bus binding, typically due to connectivity issues, authentication failures, or provider errors.

**Handler Example**:

```java
@EventHandler
public void onBindingOpenFailed(AepBusBindingOpenFailedEvent event) {
    logger.error("Failed to open binding {}: {}",
        event.getBinding().getName(), event.getCause());
}
```

**Javadoc**: [AepBusBindingOpenFailedEvent](https://build.neeveresearch.com/rumi/javadoc/LATEST/com/neeve/aep/event/AepBusBindingOpenFailedEvent.html)

***

### AepChannelUpEvent

**Package**: `com.neeve.aep.event` **Event Type**: Lifecycle **Dispatched**: When the engine successfully connects to a channel

**Description**: Dispatched when the engine has successfully connected to the bus containing a channel configured to be of interest to the microservice. This event is guaranteed to precede any messages arriving through that channel.

**Handler Example**:

```java
@EventHandler
public void onChannelUp(AepChannelUpEvent event) {
    logger.info("Channel up: {}", event.getChannel().getName());
}
```

**Javadoc**: [AepChannelUpEvent](https://build.neeveresearch.com/rumi/javadoc/LATEST/com/neeve/aep/event/AepChannelUpEvent.html)

***

### AepBusBindingUpEvent

**Package**: `com.neeve.aep.event` **Event Type**: Lifecycle **Dispatched**: When the engine has successfully established a binding

**Description**: Dispatched when a message bus binding is fully operational. This event is dispatched after the channel up events for the established binding and is guaranteed to precede any messages arriving through the binding.

**Handler Example**:

```java
@EventHandler
public void onBindingUp(AepBusBindingUpEvent event) {
    logger.info("Binding up: {}", event.getBinding().getName());
}
```

**Javadoc**: [AepBusBindingUpEvent](https://build.neeveresearch.com/rumi/javadoc/LATEST/com/neeve/aep/event/AepBusBindingUpEvent.html)

***

### AepChannelDownEvent

**Package**: `com.neeve.aep.event` **Event Type**: Lifecycle **Dispatched**: When the engine disconnects from a channel

**Description**: Dispatched when the engine has disconnected from the bus containing a channel configured to be of interest to the microservice. This event is guaranteed to succeed any messages arriving through that channel.

**Handler Example**:

```java
@EventHandler
public void onChannelDown(AepChannelDownEvent event) {
    logger.warn("Channel down: {}", event.getChannel().getName());
}
```

**Javadoc**: [AepChannelDownEvent](https://build.neeveresearch.com/rumi/javadoc/LATEST/com/neeve/aep/event/AepChannelDownEvent.html)

***

### AepBusBindingDownEvent

**Package**: `com.neeve.aep.event` **Event Type**: Alert **Dispatched**: When an operational bus binding fails

**Description**: Dispatched when a previously operational bus binding experiences a failure and goes down. This can occur due to network issues, provider failures, or other connectivity problems.

**Handler Example**:

```java
@EventHandler
public void onBindingDown(AepBusBindingDownEvent event) {
    logger.error("Binding down: {}", event.getBinding().getName());
}
```

**Javadoc**: [AepBusBindingDownEvent](https://build.neeveresearch.com/rumi/javadoc/LATEST/com/neeve/aep/event/AepBusBindingDownEvent.html)

***

### AepBusBindingDestroyedEvent

**Package**: `com.neeve.aep.event` **Event Type**: Lifecycle **Dispatched**: When the engine has destroyed a binding

**Description**: Dispatched when a bus binding is fully destroyed and cleaned up. This is the final event in the bus binding lifecycle.

**Handler Example**:

```java
@EventHandler
public void onBindingDestroyed(AepBusBindingDestroyedEvent event) {
    logger.info("Binding destroyed: {}", event.getBinding().getName());
}
```

**Javadoc**: [AepBusBindingDestroyedEvent](https://build.neeveresearch.com/rumi/javadoc/LATEST/com/neeve/aep/event/AepBusBindingDestroyedEvent.html)

***

## Store Events

### IStoreBindingFailedEvent

**Package**: `com.neeve.ods` **Event Type**: Alert **Dispatched**: When a store binding has failed

**Description**: Dispatched to indicate that a store binding has 'failed'. A binding 'failure' is a binding closure triggered implicitly by the binding on the occurrence of certain events that the binding deems fatal enough that it cannot continue operations. On a failure, a binding performs all closure operations, transitions to the failed state, and then dispatches this event.

Although permissible, it is not necessary to close a binding on a failure (since it is already implicitly closed). Note that if you choose to close the binding subsequent to a failure, the close should not be invoked from within the binding event handler. Doing so may cause a deadlock.

**Handler Example**:

```java
@EventHandler
public void onStoreBindingFailed(IStoreBindingFailedEvent event) {
    logger.error("Store binding failed: {}", event.getCause());
}
```

**Javadoc**: [IStoreBindingFailedEvent](https://build.neeveresearch.com/rumi/javadoc/LATEST/com/neeve/ods/IStoreBindingFailedEvent.html)

***

### IStoreBindingRoleChangedEvent

**Package**: `com.neeve.ods` **Event Type**: Lifecycle **Dispatched**: Before the role of a store binding member is changing

**Description**: Dispatched to notify that the role of the member represented by a store binding is changing. This event is dispatched before the binding's new role takes effect.

**Handler Example**:

```java
@EventHandler
public void onStoreRoleChanged(IStoreBindingRoleChangedEvent event) {
    logger.info("Store role changing from {} to {}",
        event.getOldRole(), event.getNewRole());
}
```

**Javadoc**: [IStoreBindingRoleChangedEvent](https://build.neeveresearch.com/rumi/javadoc/LATEST/com/neeve/ods/IStoreBindingRoleChangedEvent.html)

***

### IStoreMemberUpEvent

**Package**: `com.neeve.ods` **Event Type**: Lifecycle **Dispatched**: When a new member joins the ODS store

**Description**: Notifies that a new member has joined an ODS store cluster.

**Handler Example**:

```java
@EventHandler
public void onStoreMemberUp(IStoreMemberUpEvent event) {
    logger.info("Store member up: {}", event.getMember().getId());
}
```

**Javadoc**: [IStoreMemberUpEvent](https://build.neeveresearch.com/rumi/javadoc/LATEST/com/neeve/ods/IStoreMemberUpEvent.html)

***

### IStoreMemberDownEvent

**Package**: `com.neeve.ods` **Event Type**: Lifecycle **Dispatched**: When a member leaves the ODS store

**Description**: Notifies that a member has left an ODS store cluster.

**Handler Example**:

```java
@EventHandler
public void onStoreMemberDown(IStoreMemberDownEvent event) {
    logger.warn("Store member down: {}", event.getMember().getId());
}
```

**Javadoc**: [IStoreMemberDownEvent](https://build.neeveresearch.com/rumi/javadoc/LATEST/com/neeve/ods/IStoreMemberDownEvent.html)

***

### IStoreMemberInitCompleteEvent

**Package**: `com.neeve.ods` **Event Type**: Lifecycle **Dispatched**: When store member initialization completes

**Description**: Dispatched in the following situations:

1. On primary members after initialization from the persister is complete
2. On primary members when a new member joining the store has been successfully initialized. Follows the IStoreMemberUpEvent for the new member
3. On standalone receiver members after initialization from the persister is complete
4. On backup members after initialization from the primary is complete. Follows the IStoreMemberUpEvent for the primary member

Listen for the IStoreBindingRoleChangedEvent to keep track of role and appropriately interpret this event, or compare the member reported in this event with the member returned by `IStoreBinding.getMember()` to interpret the event.

**Handler Example**:

```java
@EventHandler
public void onStoreMemberInitComplete(IStoreMemberInitCompleteEvent event) {
    logger.info("Store member initialization complete: {}", event.getMember().getId());
}
```

**Javadoc**: [IStoreMemberInitCompleteEvent](https://build.neeveresearch.com/rumi/javadoc/LATEST/com/neeve/ods/IStoreMemberInitCompleteEvent.html)

***

## Event Handler Declaration

Events are handled using the @EventHandler annotation:

```java
import com.neeve.aep.annotations.EventHandler;
import com.neeve.aep.event.AepEngineActiveEvent;

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

**Key Points**:

* Event handler method name is arbitrary
* Method must take exactly one parameter of the event type
* Multiple handlers can handle the same event type
* Handlers are invoked in order of declaration

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

***

## Event Lifecycle Flow

Events are dispatched in a specific order during the microservice lifecycle:

### Startup Sequence

1. `AepEngineCreatedEvent`
2. `AepMessagingPrestartEvent`
3. `AepBusBindingCreatedEvent` (for each binding)
4. `AepBusBindingOpeningEvent`
5. `AepBusBindingOpenedEvent`
6. `AepChannelUpEvent` (for each channel)
7. `AepBusBindingUpEvent`
8. `AepMessagingStartedEvent`
9. `AepEngineStartedEvent`
10. `AepEngineActiveEvent` (if elected primary)

### Shutdown Sequence

1. `AepChannelDownEvent` (for each channel)
2. `AepBusBindingDownEvent` (for each binding)
3. `AepBusBindingDestroyedEvent` (for each binding)
4. `AepEngineStoppedEvent`

**See Also**: [Lifecycle](/rumi-core/concepts/microservice-operation/lifecycle.md)

***

## Event Packages

### com.neeve.aep.event

AEP Engine and messaging events (all Aep\* events)

### com.neeve.ods

Store and ODS cluster events (all IStore\* events)

***

## See Also

* [Lifecycle](/rumi-core/concepts/microservice-operation/lifecycle.md) - Complete lifecycle documentation with event dispatch points
* [Annotations](/rumi-core/reference/annotations.md) - @EventHandler and other annotations
* [Handling Messages](/rumi-core/guides/developing-applications/authoring-user-code/message-processing/processing-messages/handling-messages.md) - Event and message handling guide
* [Implementing Lifecycle Methods](/rumi-core/guides/developing-applications/authoring-user-code/lifecycle/implementing-lifecycle-methods.md) - Lifecycle hooks and event handlers


---

# 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/events.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.