Events

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

Overview

Talon 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

Talon 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

Event Categories

Events are organized by their source component:

Engine Events

Core engine lifecycle events

Messaging Events

Message bus and channel connectivity 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:

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

Javadoc: AepEngineCreatedEvent

See Also: Lifecycle - 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:

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

Javadoc: AepMessagingPrestartEvent

See Also: Lifecycle - 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:

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

Javadoc: AepMessagingStartedEvent

See Also: Lifecycle - 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:

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

Javadoc: AepMessagingStartFailedEvent

---

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:

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

Javadoc: AepEngineStartedEvent

See Also: Lifecycle - 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:

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

Javadoc: AepEngineActiveEvent

See Also: Lifecycle - 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:

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

Javadoc: AepFlowCreatedEvent

---

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:

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

Javadoc: AepStateCreatedEvent

---

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:

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

Javadoc: AepMessagingFailedEvent

See Also: MessageBusBindingFailPolicy

---

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:

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

Javadoc: AepEngineStoppedEvent

See Also: Lifecycle - 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:

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

Javadoc: AepBusBindingCreatedEvent

---

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:

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

Javadoc: AepBusBindingCreateFailedEvent

---

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:

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

Javadoc: AepBusBindingOpeningEvent

---

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:

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

Javadoc: AepBusBindingOpenedEvent

---

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:

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

Javadoc: AepBusBindingOpenFailedEvent

---

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:

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

Javadoc: AepChannelUpEvent

---

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:

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

Javadoc: AepBusBindingUpEvent

---

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:

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

Javadoc: AepChannelDownEvent

---

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:

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

Javadoc: AepBusBindingDownEvent

---

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:

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

Javadoc: AepBusBindingDestroyedEvent

---

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:

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

Javadoc: IStoreBindingFailedEvent

---

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:

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

Javadoc: IStoreBindingRoleChangedEvent

---

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:

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

Javadoc: IStoreMemberUpEvent

---

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:

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

Javadoc: IStoreMemberDownEvent

---

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:

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

Javadoc: IStoreMemberInitCompleteEvent

---

Event Handler Declaration

Events are handled using the @EventHandler annotation:

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

---

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

---

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 - Complete lifecycle documentation with event dispatch points

• Annotations - @EventHandler and other annotations

• Handling Messages - Event and message handling guide

• Implementing Lifecycle Methods - Lifecycle hooks and event handlers