Apama 10.15.0 | Connecting Apama Applications to External Components | Working with IAF Plug-ins | The Integration Adapter Framework | Architecture
 
Architecture
The first step in integrating Apama within a user environment is to connect the correlator to one or more message/event sources and/or sinks. In the majority of cases the source or provider of messages will be some form of middleware message bus although it could also be a database or other storage based message source, as well as an alternative network-based communication mechanism, like a trading system. The same applies for the sink or consumer of messages.
These message sources and/or sinks vary extensively. Typically each comes with its own proprietary communications paradigm, communications protocol, message representation and programming interfaces. Interfacing any software like Apama with a source/sink of messages like a message bus therefore requires the writing of a specialized software adapter or connector, which needs to be maintained should the messaging environment or the message representation change. The adapter needs to interface with the messaging middleware or message source, receive messages from it and decode them, and then transform them into events that Apama can understand and process. The latter transformation is not always straightforward, as the message representation might vary from message to message and require semantic understanding.
Conversely, the events generated by Apama need to be processed in the inverse direction and eventually end up back on the message bus.
Note: 
In the Apama documentation, a message traveling from a message source through the IAF and into Apama is described as traveling downstream, whereas a message output as an alert from Apama and progressing back out through the IAF towards a message sink is described as traveling upstream.
In order to facilitate development of software adapters, Apama provides the IAF. In contrast to the SDKs, the IAF is not a programming library. The IAF is effectively a customizable, middleware independent, generic adapter that can be adapted by a user to communicate with their middleware and apply their specific semantic transformations to their messages.
Illustration of the primary components to the IAF
As illustrated above, the IAF acts as the interface between the messaging middleware and the correlator. There are four primary components to the IAF:
*The Transport Layer. This is the layer that communicates with the user's message source/sink. Its functionality is defined through one or more Apama or user-provided message source/sink specific transport plug-ins, written in C, C++ or Java.
*The Codec Layer. The codec layer translates messages from any custom representation into a normalized form and vice-versa. The transformation is carried out by one of its codec plug-ins. These can be provided by Apama or by the user, and may be written in C, C++ or Java. Note that Java codec plug-ins may only communicate with Java transport plug-ins, and C/C++ codec plug-ins with C/C++ transport plug-ins.
*The Semantic Mapper. This layer provides functionality to transform the messages received from the message source into Apama events. The Semantic Mapper is a standard component that is configured for use with a particular adapter by means of a set of semantically rich translation mapping rules. These rules define both how to generate Apama events from externally generated messages and how user-custom messages for an external destination may be generated from Apama events.
An adapter can be configured to bypass this kind of mapping in the Semantic Mapper. Used this way, the Semantic Mapper converts the string form of an Apama event directly to a normalized form and vice-versa.
*The Apama Interface layer. This layer abstracts away communication with Apama's correlator. It injects EPL definitions and event instances into the correlator and asynchronously receives back events from it.
Additionally, the engine_send and engine_receive tools can be run against the IAF simply by supplying the port on which the IAF is running. For example, running
engine_receive -p 16903
connects to the IAF running on the default port and receives all event emitted by it.
The next sections explore the transport, codec and Semantic Mapper layers in more detail.