Enabling automatic creation of Universal Messaging channels
Note: | The information in this topic is deprecated. It applies to the old Universal Messaging integration which will be removed in a future release. It is recommended that you use the new Universal Messaging connectivity plug-in. |
For an Apama application to use Universal Messaging channels, the default behavior requires you to use Universal Messaging Enterprise Manager or Universal Messaging client APIs to create those channels. You can change the default behavior so that a Universal Messaging channel can be automatically created if it does not already exist when an Apama application needs to use it.
To enable automatic creation of Universal Messaging channels, create a Universal Messaging configuration properties file. In Software AG Designer, the default name of this file is UM-config.properties. In the properties file, specify the following properties:
Set the
um.channels.prefix property to a string. The default is
"UM_".
Set the
um.channels.mode property to
autocreate or
mixed.
When set to autocreate, Apama looks up only channels whose names begin with the specified prefix. If the channel does not exist it is created. For example, if the default prefix is used, channel names must start with UM_ for the channel to be a Universal Messaging channel.
When set to mixed, Apama looks up each channel to determine if it is a Universal Messaging channel. If the channel does not exist then it is created only if it has the prefix specified by the um.channels.prefix property.
An advantage of specifying autocreate is that Apama does not look up channel names that do not begin with the specified prefix. This can improve performance especially if non-Universal Messaging channel names are generated automatically, which might create many channels.
Setting the um.channels.mode property to mixed can be beneficial when you want to have two sets of channels. One set of channels, perhaps one per user, would be automatically created when needed and would be managed by Apama. The names of these channels would all start with the specified prefix. The other set of channels would be externally managed. This set might require channel attributes that are different from the attributes of the Apama-managed channels. Each channel in this set could have attributes that are different from any other channel.
If you do not specify the um.channels.prefix property and you set the um.channels.mode property to autocreate or mixed then channels whose names begin with UM_ can be automatically created.
By default, the
um.channels.mode property is set to
precreate, which requires
Universal Messaging channels to be created by using
Universal Messaging Enterprise Manager or
Universal Messaging client APIs, for example, see
nSession.createChannel in the Enterprise Client API for Java section of the
Universal Messaging documentation (you can access this via the
Universal Messaging webhelp). Apama looks up all channels (except the default
"" channel) to determine whether they are
Universal Messaging channels. If a channel does not exist as a
Universal Messaging channel it is not created.
The following table compares the behavior of the settings for um.channels.mode:
Sample Channel Name | precreate | mixed | autocreate |
UM_myChannel | Look up. Never create. | Look up. Can create. | Look up. Can create. |
myChannel | Look up. Never create. | Look up. Never create. | Never look up. Never create. |
After you create a Universal Messaging configuration properties file with the desired settings for the um.channels.mode and um.channels.prefix properties, do the following:
When you start a correlator that uses
Universal Messaging, specify the
--umConfigFile option with the name of your
Universal Messaging configuration properties file name. Do not specify the
--rnames option when you start the correlator.
For an IAF adapter that you want to use
Universal Messaging, in its configuration file, in the
<universal-messaging> element, set the
um-properties attribute to the name of your
Universal Messaging configuration properties file.
The recommendation is to use the same Universal Messaging configuration properties file for all Apama components.
When a
Universal Messaging channel is automatically created it has the attributes described in
Setting up
Universal Messaging
for use by Apama. If you want a
Universal Messaging channel to have any other attributes then you must create the channel in
Universal Messaging before any Apama component sends to or subscribes to the channel.
When missingChannelMode is set to create across multiple hosts, by default, all the hosts can publish or subscribe to events on the created channel (applies to creating user only).
After Apama looks up a channel name to determine whether it is a Universal Messaging channel, Apama caches the result and does not look it up again. Consequently, the following situation is possible:
1. You use Universal Messaging interfaces to create channels.
2. You start a correlator with um.channels.mode set to precreate.
3. Apama looks up, for example, channelA and determines that it is not a Universal Messaging channel.
4. You use Universal Messaging interfaces to create, for example, channelA.
For Apama to recognize channelA as a Universal Messaging channel, the correlator must be restarted.
