Overview
This page assumes you have read Working with Messaging to understand the basics of SMA messaging.
Understanding Message Send
Messages are sent over message bus channels in a fire and forget fashion - the application can rely on the underlying AepEngine to deliver the message according the quality of service configured for a channel. An application views message channels as a logical, ordered conduits over which messages flow.
The diagram below depicts the path of a message sent through an engine. The basic flow of sending is as follows:
- Application creates a message
- Application calls send passing the message and channel name.
- The engine looks up the channel and use it to resolves the physical topic on which the message will be sent
- The engine queues the message for send until the associated state changes are stabilized.
Solicited vs Unsolicited Sends
When an outbound message is sent from within an application event handler, it is refered to as a solicited send. When an application is sent from outside of a message handler it is refered to as an unsolicited send.
Because the AepEngine and underlying SMA message channels are not designed to be thread safe, it is not permissible for an AepEngine to be used concurrently for both solicited and unsolicited sends.
Creating Messages
Message types generated by the application data modeler can be created via their static create() method. Application code populates message contents as a regular pojo.
Message Concurrency and Pooling
Outbound messages sent by the application may be serialized in background threads,. So:
Once a message is sent it may not be modified or resent by the application. This includes any nested entities on the message.
An application that would like to send the same message multiple times can use the copy() method on the message. The copy can be modified and used in a subsequent send call.
Message may also be pooled by the platform. This is the reason that message construction is done through static create methods. Once the platform has finished sending them, their backing contents can be wiped and the view reused in a subsequent sent. So:
Sending a message through an AepEngine transfers ownership of the message to the engine. When a message is sent from within an application event handler, the application may not retain the message or any of its nested entities beyond the scope of the message handler as pooling may invalidated them.
Furthermore, unsolicited senders, must consider sent messages to be immediately invalid because the sending thread is outside of the context of a transaction and can have no expectation as to when the platform will dispose of the message. An unsolicited sender may call acquire() on the message prior to sending it if it needs to hold on the message for a period of time after send, but it still may not modify or reuse.
If a message is created. but not sent, it is up to the application to call dispose() on the message to return it the pool. Failing to return the message to a pool will not result in a memory leak, but it will mean that subsequent create calls won't result in object allocation and promotion.
Sending Messages
Using Aep Message Sender
SINCE 3.5
The simplest way to send a message is to add an AppInjectionPoint annotation that allows the XVM to inject a message sender. The application then supplies the bus and channel name along with the message.
See also:
Sending via the AepEngine
When not using the AepMessageSender an application must provide the MessageChannel in the AepEngine's sendMessage call. When using this pattern the application can register event handlers for channel up and down events which are dispatched to the application when messaging is started or stopped. The application can qualify the EventHandler annotation to identify a particular channelName@busName to specify the channel of interest:
Channel Keys and Dynamic Topics
The channel key is used to
Channel key of "OrderEvents/${OrderState}/${Region}/{Department}", one can specify a channel filter
Message Reflectors
Key Resolution Tables
In many cases substitution values for a dynamic key would come from the application environment or configuration. Message channels can be configured with a key resolution to allow substitution of key variables that don't come from the message being sent.
Message Sequencing
HA Considerations
Only the primary instance of an application will establish messaging connections
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),