Enabling automatic creation of UM channels
For an Apama application to use UM channels, the default behavior requires you to use UM Enterprise Manager or UM client APIs to create those channels. You can change the default behavior so that a UM channel can be automatically created if it does not already exist when an Apama application needs to use it.
To enable automatic creation of UM channels, create a UM 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 UM channel.
When set to mixed, Apama looks up each channel to determine if it is a UM 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-UM 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 UM channels to be created by using UM Enterprise Manager or UM 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 UM channels. If a channel does not exist as a UM 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 UM 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 UM, specify the
--umConfigFile option with the name of your UM configuration properties file name. Do not specify the
--rnames option when you start the correlator.
For an IAF adapter that you want to use UM, in its configuration file, in the
<universal-messaging> element, set the
um-properties attribute to the name of your UM configuration properties file.
The recommendation is to use the same UM configuration properties file for all Apama components.
When a UM channel is automatically created it has the attributes described in
Setting up UM for use by Apama. If you want a UM channel to have any other attributes then you must create the channel in UM before any Apama component sends to or subscribes to the channel.
After Apama looks up a channel name to determine whether it is a UM channel, Apama caches the result and does not look it up again. Consequently, the following situation is possible:
1. You use UM 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 UM channel.
4. You use UM interfaces to create, for example, channelA.
For Apama to recognize channelA as a UM channel, the correlator must be restarted.
When using auto-create mode across multiple hosts, by default, only the host that created the channel can publish events to the channel (other hosts can receive events from the channel). To change this, you need to set the realm server's default channel umask to
0777. See the information on server parameters in the
Universal Messaging documentation.
This setting means that whenever any client (Apama or other) creates a UM channel, it is accessible to all users connected to the realm, unless ACLs (access control lists) are specified when creating the channel or an administrator modifies the ACLs.
