Considerations for using UM channels

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 UM message bus can be configured to throttle or otherwise limit events, in which case not all events sent to a channel will be processed. See Starting correlators that use UM.

Only events can be sent or received by means of UM. You cannot use UM 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 UM 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 utility might be a better choice than using a UM channel.

UM channels can be configured for fixed capacity, and that is the default configuration used if the correlator creates a UM 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 UM channels creating a deadlock.

It is possible to use the UM client libraries (available for Java, C#, C++ and other languages) to send events to or receive events from Apama correlators and adapters.

While it is not recommended, it is possible to specify the name of a UM channel when you use these Apama interfaces. Even though you specify the name of a UM channel, UM 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 UM channels to send events to and receive events from Apama components. See About events transported by UM.

However, the UM configuration described here is intended for communication among Apama correlators and adapters. If third-party applications are using UM to transfer events, then it may be more appropriate to access those events by means of correlator-integrated messaging for JMS, which allows mapping between Apama events and XML payloads on a JMS message bus. If formats other than XML are used, an adapter that translates from those message formats to Apama events can be used. See Using Correlator-Integrated Messaging for JMS.

The name of an Apama channel can contain any UTF-8 character. However, the name of a UM channel is limited to the following character set:

Consequently, some escaping is required if UM needs to work with an Apama channel name that contains characters that are not supported in UM 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 UM, for example in a UM client application for Java, you will need to consider escaping.

When creating UM 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 UM channel names. To use those same channels with UM, you need to create the channels in UM and when you do you must escape the unsupported characters.

The escape sequence is the pound (hash) symbol, followed by the UTF-8 character number in hexadecimal (lowercase), followed by the pound (hash) symbol. For example, the following sequence would be used to escape a period in a channel name:

Suppose that in UM you want to create a channel whose name in Apama is My.Channel. In UM, you need to create a channel with the following name:

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 UM connections. This can be configured by setting the um.session.pool property in the configuration file (see Defining UM properties for Apama applications).