Apama 10.15.0 | Developing Apama Applications | Developing Apama Applications in EPL | Defining Event Listeners | Out of band connection notifications
 
Out of band connection notifications
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
*ReceiverConnected
*SenderConnected
*ReceiverDisconnected
*SenderDisconnected
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:
"name"
If no name is provided, however, the component name is as follows:
"name (on port port_number)"
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.
Note: 
You can also enable out of band notifications for a correlator with the engine_management tool and its -r setOOB on option. Be sure to inject the event definitions before running the tool with that option. For more information about using the engine_management tool, see Shutting down and managing components.