Configuring adapters to use UM
If you are configuring your Apama application to use Software AG's Universal Messaging, you can configure an adapter to use the UM 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:
Required specification of the
realms attribute
or the
um-properties attribute.
Required specification of the
<subscriber> element.
Optional specification of the
defaultChannel attribute.
Optional specification of the
enabled attribute, which indicates whether the deployed adapter uses the configuration specified in this
<universal-messaging> element.
Specification of realms or um-properties attribute
Specification of the realms attribute or the um-properties attribute is required.
The realms attribute can be set to a list of UM 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 UM realms in the order in which you specify them here. Semicolons indicate that the adapter can try to connect to the specified UM realms in any order. See
Starting correlators that use UM for more information.
If you specify more than one
RNAME, each UM realm you specify must belong to the same UM cluster. Specification of more than one UM 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 properties file that contains UM configuration settings. See
Defining UM properties for Apama applications.
Specification of subscriber element
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 UM channels this adapter receives events from. Use a comma to separate multiple channel names.
Specification of defaultChannel attribute
Specification of the defaultChannel attribute is optional. If specified, set the defaultChannel attribute to the name of a UM 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 UM must send each event to a named channel. An adapter that is configured to use UM 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 UM.
All events sent by the adapter on channels that are UM 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 utility.
Specification of the enabled attribute
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 UM. The deployed adapter uses only its explicitly set connections.
Subscribing to receive events from an adapter that is using UM
In each context, in any correlator, that is listening for events from an adapter that is using UM, 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.
Adapter configuration examples
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>
