Out of band connection notifications

When a sender and receiver component, such as a correlator, connects to or disconnects from the Integration Adapter Framework (IAF), the IAF automatically sends out of band notification events to adapter transports.

Out of band events make it possible for a developer of an adapter to add appropriate actions for the adapter to take when it receives notice that a component has connected or disconnected. For example, an adapter can cancel outstanding orders or send a notification to an external system. In order to make use of the out of band events, adapters need to provide suitable mapping in the adapter configuration file. Adapters are also free to ignore these events.

For general information about using out of band notifications, see Out of band connection notifications. Keep in mind that the OutOfBandConnections event, which is mentioned in that topic, is used to get only the senders and receivers that are connected to correlator.

Mapping example

Out of band events will only be received by codecs and transports if the semantic mapper is configured to allow them through. The semantic mapper should be configured as for any other set of events which it may wish to pass down. For more information on creating semantic mapping rules, see The event mapping rules.

For example:

<event package="com.apama.oob" name="ReceiverDisconnected"
       direction="upstream" encoder="$CODEC$" inject="false">
  <id-rules>
    <upstream />
  </id-rules>
  <mapping-rules>
    <map type="string" default="OutOfBandReceiverDisconnected"
         transport="_name" />
    <map apama="physicalId" transport="physicalId" default="" type="string" />
    <map apama="logicalId" transport="logicalId" default="" type="string" />
  </mapping-rules>
</event>
<event package="com.apama.oob" name="ReceiverConnected"
       direction="upstream" encoder="$CODEC$" inject="false">
  <id-rules>
    <upstream />
  </id-rules>
  <mapping-rules>
    <map type="string" default="OutOfBandReceiverConnected"
         transport="_name" />
    <map apama="name" transport="appname" default="" type="string" />
    <map apama="host" transport="address" default="" type="string" />
    <map apama="physicalId" transport="physicalId" default="" type="string" />
    <map apama="logicalId" transport="logicalId" default="" type="string" />
  </mapping-rules>
</event>
<event package="com.apama.oob" name="SenderDisconnected"
       direction="upstream" encoder="$CODEC$" inject="false">
  <id-rules>
    <upstream />
  </id-rules>
  <mapping-rules>
    <map type="string" default="OutOfBandSenderDisconnected"
         transport="_name" />
    <map apama="physicalId" transport="physicalId" default="" type="string" />
    <map apama="logicalId" transport="logicalId" default="" type="string" />
  </mapping-rules>
</event>
<event package="com.apama.oob" name="SenderConnected" direction="upstream"
       encoder="$CODEC$" inject="false">
  <id-rules>
  <upstream />
  </id-rules>
  <mapping-rules>
    <map type="string" default="OutOfBandSenderConnected" transport="_name" />
    <map apama="name" transport="appname" default="" type="string" />
    <map apama="host" transport="address" default="" type="string" />
    <map apama="physicalId" transport="physicalId" default="" type="string" />
    <map apama="logicalId" transport="logicalId" default="" type="string" />
  </mapping-rules>
</event>

The events are transmitted to signify the following events:

  • ReceiverConnected — an external receiver has connected; the IAF can now send events to it.
  • ReceiverDisconnected — an external receiver has disconnected; events will not be sent to this external receiver until it reconnects.
  • SenderConnected — an external sender has connected. This external sender may send events following this event.
  • SenderDisconnected — an external sender has disconnected. No more events will be received from this sender until a new SenderConnected message event is received.

However, adapters can make use of a disconnect message to not transmit events until such time as a connect occurs. For example, an adapter can coalesce events or tell external system to stop sending. Note that if multiple senders and receivers are connected and disconnected, the adapter will need to keep track of which one is connected.

Ordering of out of band notifications

The following guidelines describe when out of band connection and disconnection messages are received, and how this interacts with the framework provided to IAF adapters:

Transports and codecs will not be sent events until after their start function has been called and completed. Transports should not start generating events until their start function has been called. The first event that is delivered after the start function is called will be a SenderConnected or ReceiverConnected event, if the semantic mapper is configured to pass them through. An adapter will always receive the SenderConnected before it begins to receive any other events, but the ordering of the ReceiverConnected and SenderConnected events is not guaranteed.

If a correlator (or other component) disconnects or terminates while the adapter is running, the adapter will receive both ReceiverDisconnected and SenderDisconnected events. Again, the ordering of these events is not guaranteed. Once a SenderDisconnected event is received, no further events from that correlator will be received until a SenderConnected event is received. When a ReceiverDisconnected event is received, no more events will be sent to that correlator until a ReceiverConnected event is received. Note that in this situation, some previously sent events may not yet have reached that correlator. The events will be discarded (or sent to other receivers, if other receivers are connected).

On a reload of an adapter, the adapter will be stopped, new configuration loaded, and the adapter restarted. During this period, the IAF will not drop its connection unless the configuration of which components to connect to has changed. As such, if prior to stopping for a reload the correlator was connected, it is safe to assume that it remains connected unless, on reload, the adapters receive SenderDisconnected or ReceiverDisconnected events.

During a reload, the IAF can also load new adapters. In this event, as the IAF may already have a connection open, no ReceiverConnected or ReceiverDisconnected event may be received by the new adapters. It is thus recommended to not change transports and codecs when reconfiguring the IAF if the adapters depend on receiving the out of band events. In practice, it is unusual to change the loaded transports or codecs.

Once an adapter has entered a stopped state, it will not receive any further events (unless it later re-enters a started state). Since the shutdown order of the IAF is to move all adapters to their “stopped” state, then disconnect from downstream processes, adapters will not receive a final “disconnected” event. Therefore, the adapter may need to notify external systems on the stop function being called, as well as on disconnected events.

The following topics describe the ordering the transport will see of calls to start, stop and the transport receiving out of band and normal events.

When starting the IAF

  • IAF begins initialization
  • Adapters initialize
  • IAF connects to correlator
  • [IAF receives SenderConnected and ReceiverConnected - these are queued]
  • Adapter changes state to Started
  • Prior to receiving any other events, the semantic mapper (and then codec and adapter) receive the now unqueued out of band SenderConnected and ReceiverConnected events.
  • The SenderConnected event will arrive before any other events from said sender are delivered

IAF shutdown requested

  • Adapters state changes from started to stopped
  • IAF disconnects from correlator
  • Because transport is in state “stopped”, no events are received
  • IAF terminates

IAF Configuration Reload

  • Transport is in state “started”
  • IAF transitions transport to state “stopped”
  • IAF keeps its connection to the correlator up
  • IAF transitions transport to state started
  • Transport checks state, notices that it believes a connection is up, and continues to work without any changes

IAF Configuration reload changes correlator connection

  • Transport is in state “started”
  • IAF transitions transport to state “stopped”
  • IAF breaks its connection to the correlator
  • IAF receives ReceiverDisconnected and SenderDisconnected
  • Since the transports are stopped, these events are queued
  • IAF opens a new connection to a new correlator
  • IAF receives ReceiverConnected and SenderConnected
  • Since the transports are stopped, these events are queued
  • IAF transitions transport to state started
  • Transport checks state, notices that it believes a connection is up, and continues to work without any changes
  • Prior to receiving any other events, the ReceiverDisconnected and SenderDisconnected events are received
  • Following these, but prior to receiving any other events, the ReceiverConnected and SenderConnected events are received
  • The transport can then behave as if a new connection has been made

Correlator dies (and a new one is started) while the IAF is running

  • Transport is in state “started”
  • Correlator breaks its connection to the IAF
  • IAF receives ReceiverDisconnected and SenderDisconnected
  • Transport receives ReceiverDisconnected and SenderDisconnected
  • Following SenderDisconnected no more events should arrive from the correlator
  • Time passes
  • A new correlator makes a connection to the IAF
  • IAF receives ReceiverConnected and SenderConnected
  • Transport receives ReceiverConnected and SenderConnected
  • The transport can now behave as if a new connection has been made