The Talon Manual

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 7 Next »

Overview

This page documents the lifecycle of an X application. The lifecycle of an X application is a composite of the following:

  • The lifecycle of the application as driven by a Talon XVM.
  • The lifecycle of the application's AEP engine.
  • The lifecycle of the application's AEP engine's message bus bindings.
  • The lifecycle of the application's AEP engine's store.

This page describes each of the above and also the flow for the constituent flows of the engine and store lifecycle. These constituent flows are:

  • Engine
    • Create Engine
    • Start Engine
    • Activate Engine
    • Stop Engine
  • Store
    • Open Store Binding
    • Close Store Binding

The page presents the lifecycle and flows in a top down manner.

Application Lifecycle

An X application's lifecycle starts when the application main class is loaded by a Talon XVM and ends when the server invokes the method on the application's main class annotated with the @com.neeve.server.app.annotations.AppFinalizer annotation. The following depicts the application flow from a Talon XVM's standpoint.

ApplicationLifecycle

Load Phase

Load Application Main Class

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

Discover Lifecycle Methods

After loading the application 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 server are skipped during the application lifecycle. The various lifecycle methods and the annotations used to discover them are documented in the appropriate section below.

Open Phase

Inject Application Loader

In this step, the Talon XVM injects the application loader into the application using the loader injection method on the main application class. The application loader provides facilities to gain access to additional objects, such as the application and server configuration descriptors, that are maintained by the Talon XVM.

Get HA Policy

Next, the Talon XVM uses the @com.neeve.server.app.annotations.AppHAPolicy annotation on the main application class to query the application's HA Policy.

Prepare Engine Descriptor

The Talon XVM then instantiates the descriptor used to configure the application's AEP Engine. The descriptor is instantiated by loading the descriptor from X configuration repository if it is present in the repository. 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 then injects the engine descriptor into the application for any modifications the application would like to make on the descriptor. This is done using the engine descriptor injection method in the main application class. 

 

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 application. Prior to this phase in the lifecycle, any configuration values must be retrieved programatically via the XRuntime class.

Discover Config Injected Objects

Config Injection

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

Get Command Handler Containers

After config injection, the Talon XVM moves onto parsing the application's command handlers. This is done by first using the following method on the application's main class to fetch the set of application objects that contain the application's command handlers and then parse those objects for command handlers. 

 

Discover Command Handlers

Command handler methods are annotated with the @com.neeve.server.app.annotations.AppCommandHandler annotation. The following is an example of a command handler.

After collating all the command handler container objects obtained via the previous step, the server then parses the objects for command handlers.

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

Get AppStat Containers

Along with discovering command handlers, the Talon XVM also discovers additional objects that contain @AppStats. This is done by first using the following method on the application's main class to first fetch the set of application objects that contain the application's AppStats, and then introspecting those objects .  

 

Discover AppStats

AppStats can be be exposed by either methods or fields on the App's main class or in one of the AppStatContainers exposed above by annotating the field or method with the @com.neeve.server.app.annotations.AppStat annotation. Introspection for application stats is done just before the AepEngine is injected into the application. See User Defined App Stats for additional details. 

Get Event Handler Containers

After parsing the command handlers, the Talon XVM parses the application's event handlers. This is done by using the following method on the application's main class to first fetch the set of application objects that contain the application's event handlers and then parsing those objects for event handlers. 

Discover Event Handlers

Event handler methods are those that are annotated with the @com.neeve.aep.annotations.EventHandler annotation. Event handlers are single argument methods that contain an event or a message type as their argument. The Talon XVM and AEP engine dispatch events to the application event handlers. The following are some examples of event handlers.

After collating all the event handler container objects obtained via the previous step, the server then parses the objects for event handlers. The parsed event handlers are used by both the server and the AEP engine to dispatch events to the application.

 

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

Get Default Event Handler

Next, the server fetches the application's default event handler via the method annotated with @com.neeve.server.app.annotations,AppEventHandlerAccessor on the application main class. 

Depending on configuration, the default event handler is used to either dispatch events that are not handled by any other event handler (DefaultHandlerDispatchPolicy=DispatchIfNoAnnotatedHandlers (default)) or to always dispatch events regardless of whether the event was dispatched to other annotation based event handlers or not (DefaultHandlerDispatchPolicy=DispatchAlways)

Get Application State Factory

The final step performed by the server before creating the application's engine is to fetch the application's state factory (for State Replicated applications). This is done via the method on the application's main class annotated with the @com.neeve.server.app.annotations.StateFactoryAccessor annotation.

Create Engine

At this point, the server has all the information needed to create the application's AEP engine. The engine is thus created in this step. See below for more detail on the engine creation flow.

Inject Engine

After creating the engine, the server injects the engine into the application's main class. This is done by using the engine injection method in the main application class. 

 

Initialize Application

The final step in this phase of the application lifecycle is to initialize the application. This is done via the method on the application's main class annotated with the @com.neeve.server.app.annotations.AppInitializer annotation.

Start Phase

Start Engine

The only act performed in the start phase is to start the engine. The act of starting the engine will determine whether the started engine is the primary or a backup in the application's cluster. If primary, messages will start flowing to the application. If backup, messages and/or state will be 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 will open its messaging machinery and messages will start flowing to the application for processing. See below for more detail on the engine start flow.

Run Phase

Event Driven Applications

X Applications are message/event driven applications. For such applications, nothing additional needs to be done to enter the run phase. Once the engine has been started, messages and/or events will be dispatched to the application thus driving its operation. 

Synchronous Applications

For applications that are not event driven, i.e. "sender" only type applications that synchronously drive their own operation, the server provides the facility for the applications to implement the "main" method. The server identifies the method in the application's main class annotated with @com.neeve.server.app.annotations.AppMain to be the application's main method. If such a method is discovered, then the server spins up a separate thread that invokes the application main method. The following is an example of an application main method.

Stop Phase

Stop Engine

The only act performed in the stop phase is to stop the engine. See below for more detail on the engine stop flow.

Close Phase

Finalize Application

The last step executed by the Talon XVM in the application lifecycle is to invoke the application's finalize method, i.e. the method in the application's main class annotated with the @com.neeve.server.app.annotations.AppFinalizer annotation

Engine Lifecycle

The following depicts the overall lifecycle of an AEP engine. 

EngineLifecycle

Create Engine

The following depicts the creation flow of an AEP engine.

EngineCreate

Start Engine

The following depicts the start flow of an AEP engine.

EngineStart

Activate Engine

The following depicts the activation flow of an AEP engine.

EngineActivate

Stop Engine

The following depicts the stop flow of an AEP engine.

EngineStop

Store Lifecycle

Open Store Binding

The following depicts the open flow of an ODS store.

StoreOpen

Close Store Binding

The following depicts the closure flow of an ODS store.

StoreClose

Event Detail

Engine Events

Event TypeDescription
AepEngineCreatedEventThis event is dispatched to an application to notify it that the AEP engine has been successfully created.
AepMessagingStartFailedEventThis event is dispatched to an application to notify it that the AEP engine failed to start its messaging machinery. This event is dispatched after the engine has attempted to establish the application's message bus bindings and join any configured channels. For bindings that were successfully established, the application would have received the coresponding binding and channel up events before this event is dispatched.
AepMessagingPrestartEventThis event is dispatched to an application to notify it that the AEP engine is about to start its messaging machinery. This event is dispatched before the engine attempts to establish the application's message bus bindings and join any configured channels.
AepMessagingStartedEventThis event is dispatched to an application to notify it that the AEP engine has started its messaging machinery. This event is dispatched after the engine has attempted to establish the application's message bus bindings and join any configured channels. For bindings that were successfully established, the application would have received the corresponding channel up events before this event is dispatched.
AepEngineActiveEventThis event is dispatched to an application to notify it that the AEP engine has been elected as primary and has successfully started its messaging machinery. This event is dispatched after the engine has successfully established the application's message bus bindings and join any configured channels. For bindings that were successfully established, the application would have received the corresponding binding and channel up events before this event is dispatched.
AepEngineStartedEvent

This event is dispatched to an application to notify it that the AEP engine has been successfully started.

AepFlowCreatedEventThis event is dispatched when the AEP engine creates a new AepFlow. AepFlows are created when a message is processed either during steady state on an primary or backup instance or during recovery for a flow that does not yet exist in the engine.
AepStateCreatedEventThis event is dispatched to an application to notify it that an instance of its state has been created. This event is only dispatched on a backup AEP engine instance.
AepMessagingFailedEventThis event is dispatched to an application to notify it that the AEP engine has shut down its messaging due to a failure. This event is dispatched after the engine has shut down all the established message bus bindings. Whether and how an engine decides to shut down the messaging is determined by the AepEngine.MessageBusBindingFailPolicy.
AepEngineStoppedEventThis event is dispatched to an application to notify it that the AEP engine has been stopped.

Messaging Events

Event TypeDescription
AepBusBindingCreatedEventThis event is dispatched when the AEP engine has created a binding to a message bus. This event is dispatched before the binding is opened or started.
AepBusBindingCreateFailedEventThis event is dispatched when the AEP engine encounters a failure when trying to create a bus binding.
AepBusBindingOpeningEventThis event is dispatched just before an AEP engine starts opening a binding to a message bus. This event is followed by a binding open or binding open fail event.
AepChannelUpEventThis event is dispatched when the AEP engine has successfully connected to the bus containing a channel configured to be of interest to the AEP application (via the engine's configuration descriptor). The event is guaranteed to precede any messages arriving through that channel.
AepBusBindingUpEventThis event is dispatched when the AEP engine has successfully established a binding to a message bus. The event is dispatched after the channel up events for the established binding and is guaranteed to precede any messages arriving through the established binding.
AepBusBindingOpenedEventThis event is dispatched when the AEP engine has succesfully opened a bus binding.
AepBusBindingOpenFailedEventThis event is dispatched when the AEP engine encounters a failure when trying to open a bus binding.
AepChannelDownEventThis event is dispatched when the AEP engine has successfully disconnected from the bus containing a channel configured to be of interest to the AEP application (via the engine's configuration descriptor). The event is guaranteed to succeed any messages arriving through that channel.
AepBusBindingDownEventThis event is dispatched when an operational bus binding fails.
AepBusBindingDestroyedEventThis event is dispatched when the AEP engine has destroyed a binding to a message bus. This event is dispatched before the binding is opened or started.

Store

  
IStoreBindingFailedEventA store binding dispatches this event to indicates that it has 'failed'. A binding 'failure' is, essentially, a binding closure triggered implicitly by a 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 to the user. Although it is permissible to do, it is not necessary to close a binding on a failure (since it is already implicitly closed). Note that, if the user does 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.
IStoreBindingRoleChangedEventThis event is dispatched to the user to notify that the role of the member represented by a store binding is changing. The event is dispatched before the binding's new role takes effect, i.e. a user's query to retrieve the binding's role will return the old role.
IStoreMemberUpEventThe event notifies that a new member has joined an ODS store.
IStoreMemberDownEventThis event notifies that a member has left an ODS store.
IStoreMemberInitCompleteEvent

This event is 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. It 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 the primary is complete. It follows the IStoreMemberUpEvent for the primary member. 

The user should listen for the IStoreBindingRoleChangedEvent to keep track of its role and appropriately interpret this event, or compare the member reported in this event with the member returned by the IStoreBinding.getMember() method to interpret the event.

  • No labels