Lifecycle

This page documents the lifecycle of a Talon microservice, describing the order in which microservices are started and shutdown, and the events emitted that allow microservices to hook into this lifecycle.

Overview

The lifecycle of a Talon microservice is a composite of the following:

• The lifecycle of the microservice as driven by the Talon XVM

• The lifecycle of the microservice's AEP engine

• The lifecycle of the microservice's AEP engine's message bus bindings

• The lifecycle of the microservice's AEP engine's store

This page describes each of these lifecycles and their constituent flows:

Engine Lifecycle:

• Create Engine

• Start Engine

• Activate Engine

• Stop Engine

Store Lifecycle:

• Open Store Binding

• Close Store Binding

Microservice Lifecycle

A Talon microservice's lifecycle starts when the microservice main class is loaded by the Talon XVM and ends when the XVM invokes the method on the microservice's main class annotated with @AppFinalizer. The following diagram depicts the microservice flow from the Talon XVM's standpoint:

Microservice Lifecycle

Load Phase

Load Microservice Main Class

The first step executed by the Talon XVM is to load the microservice main class.

Discover Lifecycle Methods

After loading the microservice main class, the Talon XVM introspects the loaded class for lifecycle-related methods. Lifecycle methods are identified via annotations and are optional. Methods not found by the XVM are skipped during the microservice lifecycle.

Open Phase

Inject Application Loader

The Talon XVM injects the application loader into the microservice using the loader injection method on the main microservice class. The application loader provides facilities to access additional objects, such as the microservice and XVM configuration descriptors.

@com.neeve.server.app.annotations.AppInjectionPoint
public void setLoader(final com.neeve.server.app.SrvAppLoader loader) {...}

Get HA Policy

The Talon XVM uses the @AppHAPolicy annotation on the main microservice class to query the microservice's HA Policy.

@com.neeve.server.app.annotations.AppHAPolicy(value=EventSourcing)

Prepare Engine Descriptor

The Talon XVM instantiates the descriptor used to configure the microservice's AEP Engine. The descriptor is loaded from the X configuration repository if present; otherwise, a fresh default descriptor is instantiated. The HA policy, if obtained in the last step, is set in the engine descriptor.

Inject Engine Descriptor

The Talon XVM injects the engine descriptor into the microservice for any modifications the microservice would like to make on the descriptor.

@com.neeve.server.app.annotations.AppInjectionPoint
public void setEngineDescriptor(final com.neeve.aep.AepEngineDescriptor descriptor) {...}

Configuration Injection

Since 3.2

After the engine descriptor is prepared, the Talon XVM injects configuration values from the XRuntime environment into objects provided by the microservice.

Discover Config Injected Objects:

@com.neeve.server.app.annotations.AppConfiguredAccessor
public void addConfiguredObjects(Set<Object> objects) {...}

Config Injection:

After retrieving the set of config injected objects, the Talon XVM introspects the objects and injects configuration as described in the configuration documentation.

Get Command Handler Containers

The Talon XVM fetches the set of microservice objects that contain command handlers:

@com.neeve.server.app.annotations.AppCommandHandlerContainerAccessor
public void addCommandHandlerContainerObjects(Set<Object> containers) {...}

Discover Command Handlers:

Command handler methods are annotated with @AppCommandHandler:

@com.neeve.server.app.annotations.AppCommandHandler(command="printhelloworld")
public String helloWorld(String command, String[] args) {
   System.out.println("Hello World!");
}

Command handler container objects can also contain non-command handler methods. Those methods will be ignored by the XVM command handler parser machinery.

Get AppStat Containers

The Talon XVM discovers additional objects that contain @AppStats:

// Note that the method name is unimportant.
@com.neeve.server.app.annotations.AppStatContainersAccessor
public void addAppStatContainerObjects(Set<Object> containers) {...}

Discover AppStats:

AppStats can be exposed by fields or methods on the microservice's main class or in AppStatContainers by annotating with @AppStat. See Exposing Application Stats for additional details.

Get Event Handler Containers

The Talon XVM fetches the set of microservice objects that contain event handlers:

@com.neeve.server.app.annotations.AppEventHandlerContainersAccessor
public void addEventHandlerContainerObjects(Set<Object> containers) {...}

Discover Event Handlers:

Event handler methods are annotated with @EventHandler. Event handlers are single-argument methods that contain an event or a message type as their argument:

@com.neeve.aep.annotations.EventHandler
public void onEngineActivated(final com.neeve.aep.event.AepEngineActiveEvent event) {...}

@com.neeve.aep.annotations.EventHandler
public void onOrder(final NewOrderMessage message) {...}

Event handler container objects can contain non-event handler methods. Those methods will be ignored by the XVM and AEP engine event handler parser machinery.

Get Default Event Handler

The XVM fetches the microservice's default event handler via the method annotated with @AppEventHandlerAccessor:

@com.neeve.server.app.annotations.AppEventHandlerAccessor
public IEventHandler getDefaultEventHandler() {...}

Depending on configuration, the default event handler is used to either:

• Dispatch events not handled by any other event handler (DefaultHandlerDispatchPolicy=DispatchIfNoAnnotatedHandlers - default)

• Always dispatch events regardless of whether dispatched to other annotation-based event handlers (DefaultHandlerDispatchPolicy=DispatchAlways)

Get Application State Factory

The final step before creating the microservice's engine is to fetch the microservice's state factory (for State Replicated microservices):

@com.neeve.server.app.annotations.AppStateFactoryAccessor
public IAepApplicationStateFactory getStateFactory() {...}

Create Engine

At this point, the XVM has all the information needed to create the microservice's AEP engine. See Engine Lifecycle below for details on the engine creation flow.

Inject Engine

After creating the engine, the XVM injects the engine into the microservice's main class:

@com.neeve.server.app.annotations.AppInjectionPoint
public void setEngine(final com.neeve.aep.AepEngine engine) {...}

Initialize Application

The final step in the open phase is to initialize the microservice:

@com.neeve.server.app.annotations.AppInitializer
public void initialize() {...}

Start Phase

Start Engine

The only act performed in the start phase is to start the engine. The act of starting the engine determines whether the started engine is the primary or a backup in the microservice's cluster. If primary, messages start flowing to the microservice. If backup, messages and/or state are replicated in real time from the primary to the backup to keep the backup's state in sync with the primary. If the primary fails, the backup elected as primary opens its messaging machinery and messages start flowing to the microservice for processing. See Engine Lifecycle below for details on the engine start flow.

Run Phase

Event Driven Applications

Talon microservices are message/event driven. For such microservices, nothing additional needs to be done to enter the run phase. Once the engine has been started, messages and/or events are dispatched to the microservice, driving its operation.

Synchronous Applications

For microservices that are not event driven (i.e., "sender" only type microservices that synchronously drive their own operation), the XVM provides the facility to implement the "main" method. The XVM identifies the method in the microservice's main class annotated with @AppMain to be the microservice's main method. If such a method is discovered, the XVM spins up a separate thread that invokes the microservice main method:

@com.neeve.server.app.annotations.AppMain
public void main() {...}

Stop Phase

Stop Engine

The only act performed in the stop phase is to stop the engine. See Engine Lifecycle below for details on the engine stop flow.

Close Phase

Finalize Application

The last step executed by the Talon XVM in the microservice lifecycle is to invoke the microservice's finalize method:

@com.neeve.server.app.annotations.AppFinalizer
public void finalize() {...}

Engine Lifecycle

The following depicts the overall lifecycle of an AEP engine:

Engine Lifecycle

Create Engine

The following depicts the creation flow of an AEP engine:

Engine Create

During engine creation, the engine:

1. Initializes internal components

2. Sets up message processing infrastructure

3. Prepares for messaging and store bindings

4. Configures event dispatching

Start Engine

The following depicts the start flow of an AEP engine:

Engine Start

During engine start, the engine:

1. Participates in cluster consensus to determine role (primary or backup)

2. Initializes based on determined role

3. Prepares to activate if elected primary

Activate Engine

The following depicts the activation flow of an AEP engine:

Engine Activate

During engine activation:

1. The engine opens messaging connections

2. Joins configured channels

3. Opens store bindings if configured

4. Begins processing messages

This phase marks the transition to the engine becoming fully operational and processing messages.

Stop Engine

The following depicts the stop flow of an AEP engine:

Engine Stop

During engine stop:

1. Messaging is stopped and connections are closed

2. Store bindings are closed

3. Internal resources are cleaned up

Store Lifecycle

Open Store Binding

The following depicts the open flow of an ODS store:

Store Open

When a store binding opens:

1. Connection to the persistent store is established

2. The binding joins the store cluster

3. State initialization occurs (from persistent store or from primary)

4. The binding becomes operational

Close Store Binding

The following depicts the closure flow of an ODS store:

Store Close

When a store binding closes:

1. Any pending transactions are completed or rolled back

2. The binding leaves the store cluster

3. Connection to the persistent store is closed

4. Resources are released

Event Reference

Engine Events

Event Type	Description
AepEngineCreatedEvent	Dispatched when the AEP engine has been successfully created.
AepMessagingPrestartEvent	Dispatched before the engine attempts to establish message bus bindings and join any configured channels.
AepMessagingStartedEvent	Dispatched after the engine has attempted to establish message bus bindings and join any configured channels. Dispatched after corresponding channel up events.
AepMessagingStartFailedEvent	Dispatched when the engine fails to start its messaging machinery. Dispatched after the engine has attempted to establish bindings. For bindings that were successfully established, corresponding binding and channel up events would have been dispatched before this event.
AepEngineStartedEvent	Dispatched when the AEP engine has been successfully started.
AepEngineActiveEvent	Dispatched when the engine has been elected as primary and has successfully started its messaging machinery. Dispatched after the engine has successfully established message bus bindings and joined any configured channels. Corresponding binding and channel up events are dispatched before this event.
AepFlowCreatedEvent	Dispatched when the AEP engine creates a new AepFlow. AepFlows are created when a message is processed either during steady state on a primary or backup instance or during recovery for a flow that does not yet exist in the engine.
AepStateCreatedEvent	Dispatched when an instance of the microservice store has been created. This event is only dispatched on a backup AEP engine instance.
AepMessagingFailedEvent	Dispatched when the engine has shut down its messaging due to a failure. Dispatched after the engine has shut down all established message bus bindings. Whether and how an engine decides to shut down messaging is determined by the MessageBusBindingFailPolicy.
AepEngineStoppedEvent	Dispatched when the AEP engine has been stopped.

Messaging Events

Event Type	Description
AepBusBindingCreatedEvent	Dispatched when the engine has created a binding to a message bus. Dispatched before the binding is opened or started.
AepBusBindingCreateFailedEvent	Dispatched when the engine encounters a failure when trying to create a bus binding.
AepBusBindingOpeningEvent	Dispatched just before the engine starts opening a binding to a message bus. Followed by a binding open or binding open fail event.
AepBusBindingOpenedEvent	Dispatched when the engine has successfully opened a bus binding.
AepBusBindingOpenFailedEvent	Dispatched when the engine encounters a failure when trying to open a bus binding.
AepChannelUpEvent	Dispatched when the engine has successfully connected to the bus containing a channel configured to be of interest to the microservice. Guaranteed to precede any messages arriving through that channel.
AepBusBindingUpEvent	Dispatched when the engine has successfully established a binding to a message bus. Dispatched after the channel up events for the established binding and guaranteed to precede any messages arriving through the established binding.
AepChannelDownEvent	Dispatched when the engine has successfully disconnected from the bus containing a channel configured to be of interest to the microservice. Guaranteed to succeed any messages arriving through that channel.
AepBusBindingDownEvent	Dispatched when an operational bus binding fails.
AepBusBindingDestroyedEvent	Dispatched when the engine has destroyed a binding to a message bus.

Store Events

Event Type	Description
IStoreBindingFailedEvent	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.
IStoreBindingRoleChangedEvent	Dispatched to notify that the role of the member represented by a store binding is changing. Dispatched before the binding's new role takes effect.
IStoreMemberUpEvent	Notifies that a new member has joined an ODS store.
IStoreMemberDownEvent	Notifies that a member has left an ODS store.
IStoreMemberInitCompleteEvent	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.

See Also

• Initialization - Microservice initialization

• Message Processing - Steady state message processing

• Cluster Join - The cluster join process

• Cluster Consensus - How cluster consensus is achieved

• Cluster Failover - How cluster failover occurs

• Implementing Lifecycle Methods - How to implement lifecycle hooks in your microservices