Apama correlator configuration
The adapter configuration file requires an <apama> element, which configures how the IAF connects to the Apama correlator(s). An <apama> element can contain the following elements in the following order:
<sinks> — This element lists the Apama correlators that the IAF needs to connect with in order to inject EPL event type definitions and events. You can specify the following attribute in a
<sink> element:
parallelConnectionLimit — optional — The default behavior is that the IAF limits itself to an internally set number of connections with each specified sink. This number scales according to the number of CPUs that the IAF detects on the host that is running the IAF. While this number is usually sufficient, there are some situations in which you might want to change it. For example, if you are trying to conserve resources you might want to limit the number of connections to 1, or if you want to prevent multiple threads from sharing a connection you might allow a higher number of connections than the default allows. See the information below about multiple connections from IAF to correlator.
Each correlator is defined in its own <sink> element:
<sink> — This element defines a correlator that the IAF must send events to. You can define more than one
<sink> element. All sinks specified will be injected with any EPL event type definitions that are defined in
<event> elements in the configuration file. The following attributes are allowed in
<sink> elements:
host — Required. Defines the name or address of the host machine where the correlator is running.
port — Required. Specifies the port that this correlator can be contacted on.
sendEvents — Optional. The default behavior is that all sinks receive all events generated by the Semantic Mapper. To prevent the Semantic Mapper from sending all events to a particular correlator, add sendEvents="false" to the <sink> element that defines that correlator. No events will be sent to that correlator regardless of any channel settings.
<sources> — This element lists the Apama components (usually correlators) from which the IAF can receive events. Each component is defined in its own
<source> element:
<source> — This element defines an Apama component that the IAF needs to register with as an event consumer. This enables the IAF to receive any alerts generated by the specified component. The following attributes are allowed in
<source> elements:
host — Required. Defines the name or address of the host machine where the Apama component is running.
port — Required. Specifies the port that this Apama component can be contacted on.
channels — Required. Specifies the channels that the IAF should listen on to receive events. An empty string indicates that the IAF receives all generated events. To receive events on only particular channels, specify a comma-separated list of channel names. Do not include any spaces. For example, channels="UK,USA,GER".
disconnectable — Specifies whether or not the IAF can be disconnected if it is slow. If set to yes or true (case insensitive), the IAF can be disconnected. Any other setting specifies that it cannot be disconnected.
It is possible to define the IAF as having only sinks, or only sources, or both, or neither. If the IAF has been started with no sinks and no sources, you would use the engine_connect tool to connect it to a correlator or another IAF.
For complete information on
engine_connect, see
Correlator pipelining.
Disabling Apama messaging and using Universal Messaging instead
Note:
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.
A deployed adapter can use Software AG's Universal Messaging message bus in place of connections specified in the <apama> element. When you want to use Universal Messaging instead of explicitly set connections do the following:
Add the
enabled attribute to the
<apama> element, if you have one, and set it to
false. For example:
<apama enabled="false">.....</apama>
Alternatively, you can remove the <apama> element.
When the enabled attribute is set to "false" then the entire <apama> element is ignored. In other words, the deployed adapter does not use any connections specified in the <apama> element. Instead, the deployed adapter uses the Universal Messaging configuration specified in the <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 connections specified in the <apama> element are used.
While specifying both an <apama> element and a <universal-messaging> element in an adapter configuration file is permitted, it is not recommended.
Multiple connections from IAF to correlator
To improve performance, an IAF transport might use multiple threads to send events to the codec and thus to the Semantic Mapper. If more than one thread is sending events downstream (IAF to correlator) then for each thread, the IAF creates a new connection to each <sink> defined in the configuration file, up to the defined limit. Thus, multiple threads can deliver events in parallel to the same sink. In combination with the channelTransport attribute on events (defined in <event> elements), threads can deliver events to different channels to be received by different contexts. For optimal parallel event delivery, each IAF transport thread should send events on a distinct set of channels. There are no ordering guarantees when different threads deliver events to the same sink.
There is a limit on how many connections to each sink the IAF can create. The IAF logs the limit for the number of connections in the startup stanza. If events are sent on more threads than the number of allowed connections, then the IAF re-uses existing connections, which means that some threads share connections. If a thread terminates, the connection it is using is not closed since it might be in use by another thread. See the information above for the parallelConnectionLimit attribute on the <sink> element.
Example
Following is an example of an <apama> element: