Configuring IAF adapters to use Universal Messaging

Use of Universal Messaging from the IAF is deprecated and will be removed in a future release. It is recommended that you now change any IAF-based adapter configurations using Universal Messaging with a <universal-messaging> element in the configuration file to use an <apama> element to talk directly to the correlator. See Apama correlator configuration.

If you are configuring your Apama application to use Universal Messaging, you can configure an IAF adapter to use the Universal Messaging message bus to send and receive events. To do this, add a <universal-messaging> element to your adapter configuration file. A <universal-messaging> element can replace or follow the <apama> element.

A <universal-messaging> element contains:

Optional specification of the enabled attribute, which indicates whether the deployed adapter uses the configuration specified in this <universal-messaging> element.

Specification of the realms attribute or the um-properties attribute is required.

The realms attribute can be set to a list of Universal Messaging realm names (RNAME) to connect to. You can use commas or semicolons as separators.

Commas indicate that you want the adapter to try to connect to the Universal Messaging realms in the order in which you specify them here. Semicolons indicate that the adapter can try to connect to the specified Universal Messaging realms in any order.

If you specify more than one RNAME, each Universal Messaging realm you specify must belong to the same Universal Messaging cluster. Specification of more than one Universal Messaging realm lets you benefit from failover features. See the Universal Messaging documentation for information on Communication Protocols and RNAMEs.

The um-properties attribute can be set to the name or path of a file that contains Universal Messaging configuration settings. See also Defining Universal Messaging properties for the IAF.

Specification of the <subscriber> element is required. The <subscriber> element must specify the channels attribute. Set the channels attribute to a string that specifies the names of the Universal Messaging channels this adapter receives events from. Use a comma to separate multiple channel names.

Specification of the defaultChannel attribute is optional. If specified, set the defaultChannel attribute to the name of a Universal Messaging channel. You cannot specify an empty string. In other words, the value of the defaultChannel attribute cannot be the default Apama channel, which is the empty string.

An adapter that uses Universal Messaging must send each event to a named channel. An adapter that is configured to use Universal Messaging identifies the named channel to use as follows:

1. If the transportChannel attribute is set for an event type (in an <event> or <unmapped> element), then this is the channel the adapter uses for that event type.

2. If the transportChannel attribute is not set for an event type but the presetChannel attribute is set, then this is the channel the adapter uses for that event type.

3. If neither transportChannel nor presetChannel is set for an event type, then the adapter uses the channel set by the defaultChannel attribute in the <universal-messaging> element.

4. If neither transportChannel nor presetChannel is set and you did not explicitly set defaultChannel and you used Software AG Designer to create the adapter configuration file, then the defaultChannel attribute is set to "adapter_name adapter_instance_id. For example: "File Adapter instance 3".

5. If none of transportChannel, presetChannel, or defaultChannel are set and if you did not use Software AG Designer to create the adapter configuration file, then the adapter fails if it tries to use Universal Messaging.

All events sent by the adapter on channels that are Universal Messaging channels are delivered to those channels.

Specification of a value for the defaultChannel attribute affects events that are sent from this adapter to Apama engine clients, and from this adapter to correlators when the adapter connects to that correlator by means of the engine_connect correlator tool.

Optional specification of the enabled attribute, which indicates whether the deployed adapter uses the configuration specified in this <universal-messaging> element. The default is that the enabled attribute is set to true. If the enabled attribute is not specified or if it is set to true, then the configuration specified in the <universal-messaging> element is used.

If enabled is set to false, then the deployed adapter ignores the <universal-messaging> element and does not use Universal Messaging. The deployed adapter uses only its explicitly set connections.

In each context, in any correlator, that is listening for events from an adapter that is using Universal Messaging, at least one monitor instance must subscribe to the channel or channels on which events are sent from the adapter. For example, if you are using an ADBC adapter, you must include a monitor.subscribe(channelName) command for the corresponding instance of the ADBC adapter. Note that not all adapter service monitors support access from multiple correlators. If this is the case, then only one correlator should run the service monitors for that adapter.

Following are some examples of <universal-messaging> elements:

<universal-messaging
realms="nsp://localhost:5629"
defaultChannel="orders"
enabled="true">
<subscriber channels="UK, US, GER"/>
</universal-messaging>

<universal-messaging um-properties="UM-config.properties">
<subscriber channels="signal,forward"/>
</universal-messaging>