Apama Documentation : Connecting Apama Applications to External Components : Standard Connectivity Plug-ins : The Universal Messaging Transport Connectivity Plug-in : Overview of using Universal Messaging in Apama applications : Considerations for using Universal Messaging channels
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. See About events transported by Universal Messaging.
The following applies to the new recommended Universal Messaging integration using the connectivity plug-in: Third-party applications sending and receiving is now supported subject to having a suitable chain definition to handle the third-party message format. This is recommended over the JMS integration.
Deprecated. The following applies to the old Universal Messaging integration: The Universal Messaging configuration described here is intended for communication among Apama correlators and adapters. If third-party applications are using Universal Messaging 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 the Java Message Service (JMS).
*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.
Copyright © 2013-2017 Software AG, Darmstadt, Germany. (Innovation Release)

Product LogoContact Support   |   Community   |   Feedback