Apama applications running in the correlator can make use of Apama out of band notifications. Out of band notifications are events that are automatically sent to all public contexts in a correlator whenever any component (an IAF adapter, dashboard, another correlator, or a client built using the Apama SDKs) connects or disconnects from the correlator.

For example, consider an environment where correlator A and correlator B both have out of band notifications enabled and are connected so that events from correlator A are sent to correlator B. In this case, correlator A will receive a ReceiverConnected event and correlator B will receive a SenderConnected event. The Apama application running in correlator A and B can listen for those events and execute some application logic. Note that clients such as dashboards and IAF adapters typically connect as both receiver and a sender together and, therefore, two events would be sent in quick succession.

Out of band events are defined in the com.apama.oob package and consist of:

OutOfBandConnections contains helper functions to get currently connected senders and receivers synchronously. These functions return a sequence of ReceiverConnected events for connected receivers and sequence of SenderConnected events for connected senders. Your application can call these functions at any time and can consume the ReceiverConnected and SenderConnected events in the same way as it consumes asynchronous out of band events. This is particularly useful for getting information about connected senders and receivers which were already connected before the application was injected and whose ReceiverConnected and SenderConnected events were missed by the application. See the API Reference for EPL (ApamaDoc) for more information about the event and helper functions provided.

The ReceiverConnected and SenderConnected events contain the name of the component that is connecting. When correlators and IAF adapters send a notification event, the format of the string that contains the component name is as follows:

If no name is provided, however, the component name is as follows:

The name is the name that was specified when the component was started. For correlators and IAF adapters, you can specify a name with the --name option when you start the component (see Starting the correlator and IAF command-line options). The name defaults to correlator or iaf according to the type of component. The port_number is the port that the connecting receiver or sender is running on.

Out of band events make it possible for developers of Apama components to add appropriate actions for the component to take when it receives notice that another component of interest has connected or disconnected. For example, an adapter can cancel outstanding orders or send a notification to an external system.

To enable out of band notifications in your Apama applications, you add the Out of Band Event Notifications bundle to your project. This bundle contains the event definitions and the monitor that enables the notifications. See Adding bundles to projects or Creating and managing an Apama project from the command line for further information. In your Apama application, you have to create a listener for out of band events specific to the components in which you are interested.