> 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/developing-applications/authoring-user-code/lifecycle/initializing-the-microservice.md).

# Initializing the Microservice

Microservice initialization refers to the activities that must be performed before live message processing begins. Because these activities may read from or update the microservice store, they are carried out by injecting *initial messages* into the message stream. The initialization logic is then executed within the message handler(s) for these initial messages.

Initialization messages are specified in the `AepMessagingPrestartEvent`event handler. This event handler is invoked just before the AEP engine starts messaging for its microservice.

## Specifying the First Initialization Message

Perform the following steps, as illustrated below, to specify the first initialization message:

* Create an `AepMessagingPrestartEvent` event handler
* In the event handler, set the first message in this supplied `AepMessagingPrestartEvent`event
* Create a message handler for the first initialization message.
* Perform the initialization activities in the first message handler

```java
@EventHandler
public void onMessagingPrestart(AepMessagingPrestartEvent event) {
  event.setFirstMessage(MyFirstMessage.create());
}

@EventHandler
public void onFirstMessage(MyFirstMessage message) {
  /* do something */
}
```

## Specifying Additional Initialization Messages

In large applications composed of numerous loosely coupled event handlers, it can be beneficial to be able to register multiple initialization message handlers. The code illustrated below supplies two additional initialization messages that are used to initialize distinct code components.

```java
public class ServiceMain {
  @EventHandler
  public void onMessagingPrestart(AepMessagingPrestartEvent event) {
    event.setFirstMessage(MyFirstMessage.create());
    event.addInitialMessage(Component1InitialMessage.create());
    event.addInitialMessage(Component2InitialMessage.create());
  }
  
  @EventHandler
  public void onFirstMessage(MyFirstMessage message) {
    /* do something */
  }
}

public class ServiceComponent1 {
  @EventHandler
  public void onFirstMessage(Component1InitialMessage message) {
    /* do something */
  }
}
 
public class ServiceComponent2 {
  @EventHandler
  public void onFirstMessage(Component2InitialMessage message) {
    /*do something else*/
  }
}
```

## HA Implications for Initial Messages

Technically speaking, microservice initialization is a one-time activity performed only when a microservice instance is started for the very first time - from an empty persistent store. In contrast, the messaging prestart event -`AepMessagingPrestartEvent` - is dispatched just before a microservice instance establishes a connection to the messaging bus. This event occurs **each time an instance is elected as primary**, which can happen multiple times during the lifecycle of a microservice when any of the following occurs:

* The first instance in the microservice cluster is started
* A backup instance takes over after the primary instance fails.

This distinction is important because **initialization messages can be dispatched multiple times** over the lifetime of a microservice - each time a new primary is elected. However, **regardless of how an instance becomes primary**, its state has already been initialized *before* it establishes a messaging connection. This leads to an important consideration for all instances *except* the very first one (the one that initializes from an empty store):

* For **Event Sourced** Microservices

  * State is initialized by replaying inbound messages, including the *initial messages*.
  * These initial messages are:
    * Processed once during replay (as part of state initialization), and
      * Processed again after messaging starts, when they are re-received.

  The microservice logic must handle this duplication correctly.
* For **State Replication** Microservices:
  * Any changes made by initial message processing are already present in the replicated state.
  * When these messages are reprocessed after messaging starts, the logic must **ensure consistency** and avoid redundant state changes.

In both models, the handling of initial messages must account for prior state initialization to ensure correctness and consistency.