Considerations for using Universal Messaging channels
When using Universal Messaging channels in an Apama application, consider the following:
Injecting EPL affects only the correlator it is injected into. Be sure to inject into each correlator the event definition for each event that correlator processes. If a correlator sends an event on a channel or receives an event on a channel, the correlator must have a definition for that event.
The
Universal Messaging message bus can be configured to throttle or otherwise limit events, in which case not all events sent to a channel will be processed.
Only events can be sent or received by means of
Universal Messaging. You cannot use
Universal Messaging for EPL injections, delete requests, engine send, receive, watch or inspection utilities, nor
engine_management -r requests.
If you want events to go to only a single correlator, it is up to you to design your deployment to accomplish that. If one or more contexts in a particular correlator are the only subscribers to a particular
Universal Messaging channel, then only that correlator receives events sent on that channel. However, there is no automatic enforcement of this. In this situation, using the
engine_send correlator tool might be a better choice than using a
Universal Messaging channel.
Universal Messaging channels can be configured for fixed capacity, and that is the default configuration used if the correlator creates a
Universal Messaging channel. This does mean that if a context is sending to a channel while the same context is subscribed to that channel, then if the output queue, channel capacity and the context's input queue are all full, the send can deadlock, as the send will hold up processing the next event, but not complete if all queues are full. Similarly, avoid a cycle of contexts and
Universal Messaging channels creating a deadlock.
When the
Universal Messaging channel names are not escaped, it is possible to create or use nested channels. In this case, the slash (/) and backslash (\) characters are treated as path separators on both Windows and Linux.
CAUTION:
Apama treats slash (/) and backslash (\) as different characters while Universal Messaging treats them as identical characters (Universal Messaging generally changes a slash to a backslash). You must choose to use one of these characters in your application and standardize on this. Use of both characters as path separators will result in undefined behavior. In some circumstances, an error message indicating that the user is already subscribed to a channel may be logged when both slashes and backslashes are used.
It is possible to use the
Universal Messaging client libraries (available for Java, C#, C++ and other languages) to send events to or receive events from Apama correlators and adapters.
Universal Messaging is not used by the following:
Apama client library connections.
Correlator tools such as
engine_connect,
engine_send and
engine_receive.
Adapter-to-correlator connections defined in the
<apama> element of an adapter configuration file.
While it is not recommended, it is possible to specify the name of a Universal Messaging channel when you use these Apama interfaces. Even though you specify the name of a Universal Messaging channel, Universal Messaging is not used. Events are delivered only to the Apama components that they are directly sent to. This can useful for diagnostics, but mixing connection types for a single channel is not recommended in production.
It is possible for third-party applications to use
Universal Messaging channels to send events to and receive events from Apama components.
Third-party applications sending and receiving is supported subject to having a suitable chain definition to handle the third-party message format. This is recommended over the JMS integration.
The name of an Apama channel can contain any UTF-8 character. However, the name of a
Universal Messaging channel is limited to the following character set:
0-9
a-z
A-Z
/ (slash, used as path separator when escaping is disabled; do not use both slash and backslash characters within the same application as this will result in undefined behavior - see also the above information)
\ (backslash, used as path separator when escaping is disabled)
#
_ (underscore)
- (hyphen)
Consequently, some escaping is required if Universal Messaging needs to work with an Apama channel name that contains characters that are not supported in Universal Messaging channel names.
When writing EPL, you do not need to be concerned about escape characters in channel names. Apama takes care of this for you.
When interfacing directly with Universal Messaging, for example in a Universal Messaging client application for Java, you will need to consider escaping.
When creating Universal Messaging channels to be used by an Apama application, you might need to consider escaping. For example, you might already be using Apama channels whose names contain characters that are unsupported in Universal Messaging channel names. To use those same channels with Universal Messaging, you need to create the channels in Universal Messaging, and when you do, you must escape the unsupported characters.
The escape sequence is the hash (#) symbol, followed by the UTF-8 character number in hexadecimal (lowercase) which again is followed by the hash (#) symbol. For example, the following sequence would be used to escape a period in a channel name:
#2e#
Suppose that in Universal Messaging you want to create a channel whose name in Apama is My.Channel. In Universal Messaging, you need to create a channel with the following name:
My#2e#Channel
Universal Messaging supports different protocols. Lower latency can be achieved by using the shm (Shared Memory) protocol if both the correlator and the broker are running on the same host. See the
Universal Messaging documentation for information on how to configure the SHM driver.
Note that the SHM driver keeps a CPU core busy for each end of a connection as it uses spin loops rather than network I/O, which means that two CPU cores are used for each session. As a result, it is recommended to carefully consider and experiment with how many sessions should be used. The default number of sessions is 8, which will typically reduce throughput as it will use too much CPU for Universal Messaging connections.