Overview

This page assumes you have read Working with Messaging to understand the basics of SMA messaging.

Understanding Message Dispatch

An application's Aep Engine creates and manages the lifecycle of the message buses that an application configures for use. When an application is configured to join one of more bus channels subscriptions will be issued on behalf of the application to attract messages. Message dispatch occurs as follows:

• The message bus binding implementation receives a serialized, message provider specific message 
• Using an application supplied message view factory (generated by ADM) and SMA message data also transported with the provider specific message, the bus wraps the serialized message in a view object (also ADM generated).
• Using message metadata transported with the message, the binding looks up the message channel on which to dispatch the received message.
• The message view is then wrapped in a MessageEvent along with its message channel and is then dispatched to the application's AepEngine where it is enqueued for processing. 
• The AepEngine picks up the message event and dispatches to each application event handler that has a signature matching the message type. 
• Once the AepEngine stabilizes the results of the application's message processing, a message acknowledgement is dispatched back to the binding. 

Expressing Interest

For an application to receive messages, it must:

• join the message channels on which the message is sent
• register message factories for the bus provider to deserialize the message
• and define an EventHandler for the message

Configuring Channels For Join

In order for the application's AepEninge to issue subscriptions for the message channel on which a message is sent it must be joined. Buses and channels are configured via the platform's configuration DDL. The below configuration snippet demonstrates:

• Defining a bus named "sample-bus" with a "new-orders-channel"
• An application that uses the "sample-bus" and joins the "new-orders-channel"

Adding an EventHandler

When a message is received by a message bus it is enqueued into the application's Inbound Event Queue to be queued for dispatch, the engine will pick up 

The application's underlying AepEngine will ensure that the message is acknowledged once state changes made by the handler have been stabilized. That coupled with the engine's message deduplication features ensures that even in the event of failover, the handler will only be executed once. 

Channel Filters

A channel filter filters variable parts of a channel key to filter what is received over a message channel and is used to determine the subscriptions issued on behalf of the application. 

Channel filter take the following form: 
var1=val1[|val2][;var2=val3]

For example: given a channel key of "NEWORDERS/${Region}/{Department}", one can specify a channel filter of "Region=US|EMEA;Department=Clothing". This would join the channel on:

• NEWORDERS/US/Clothing
• NEWORDERS/EMEA/Clothing

If a variable portion of the channel key is omitted in a filter, it will result in the subscription being joined in a wildcard fashion (assuming the underlying bus implementation supports wildcards). So given a channel key of "NEWORDERS/${Region}/${Department}" and a channel filter of "Region=US|EMEA", it would result in the following subscriptions being issued during join:

• NEWORDERS/US/*
• NEWORDERS/EMEA/*

Finally, if the channel filter is set to null for the channel key in the example above, then the resulting subscription would be:

• NEWORDERS/*/*

Registering Message View Factories

Message bus binding implementations receive messages in serialized form and wrap them with a MessageView that is passed to the application to work with. MessageViews are wrapped by locating the message MessageViewFactory for the message which is typically generated by ADM. To locate the factory and message type a binding consults Message Metadata that is transported along with the serialized message. An application must therefore register the message factories it intends to use so that bus binding can find the factories. This can be done in 2 ways:

Registration via Config DDL

Most often, applications will list message view factories that they use in their DDL Config:

Programmatically

Registration can also be done programmatically via the AepEngine. A common way to do this is to provide an AppInjectionPoint for the AepEngine in the application:

Preserving Subscriptions on Shutdown

By default when an engine is stopped without an error bus channels that were 'joined' will be 'left' meaning that any subscriptions or interests created by the message bus will be unsubscribed or unregistered. This behavior can be overridden by configuring an application to preserve channel joins on stop: 

Note that this property has no effect for the case where an engine shuts down with an error (e.g. AepEngine.stop(Exception) with a non null cause. In this case channel joins are left in tact allowing a backup to take over.

This behavior can also be overridden programmatically on a case by case basis by an EventHandler for the AepEngineStoppingEvent setting AepEngineStoppingEvent.setPreserveChannelJoins(boolean),

See Also

• Processing Unhandled Messages