Sending and receiving events with connectivity plug-ins

When the correlator starts up, any connectivity chains listed in the configuration file are loaded and started. At this point, events may be sent from EPL to the chains, through all of the codecs towards the transport.

While the transport is able to send events towards the host (the correlator), the correlator does not process those events immediately. This prevents problems with events that are sent from the transport to the correlator before the correlator has had event definitions injected, or the EPL to handle those events has been injected or is ready to process the events. Instead, these events are queued in the correlator.

An EPL application that sends or receives events to a transport should call the onApplicationInitialized method on the com.softwareag.connectivity.ConnectivityPlugins EPL object. This notifies the correlator that the application is ready to process events. Any events that the transport sends towards the host (correlator) before this is called are then delivered to the correlator. Events from a transport are maintained in the correct order.

Calling onApplicationInitialized notifies all codecs and transports that the host is ready by calling the hostReady method. The transport may choose not to receive events (for example, from a JMS topic) until the application is ready if doing so may have adverse effects.

1. Apama recommends that after all an application's EPL has been injected, the application should send an application-defined "start" event using a .evt file.

2. The monitor that handles the application-defined start event (from step 1) should use this event object to notify the correlator that the application is initialized and ready to receive messages, for example:

on com.mycompany.myapp.Start() {
com.softwareag.connectivity.ConnectivityPlugins.onApplicationInitialized();
// Any other post-injection startup logic goes here too.
}

For simple applications, you can add the EPL bundle Automatic onApplicationInitialized to your project (see also Adding bundles to projects). This bundle will ensure that onApplicationInitialized is called as soon as the entire application has been injected into the correlator. However, in cases where you need to wait for a MemoryStore, database or another resource to be prepared before your application is able to begin to process incoming messages, you should not use the bundle. In these cases, you should write your own start event and application logic.

To aid diagnosing problems when part of the system is not ready in a timely manner, the correlator logs this on every Status: log line (by default, every 5 seconds). For example:

Application has not called onApplicationInitialized yet - 500 events from connectivity transports will not be processed yet

If EPL has not yet called onApplicationInitialized or if a plug-in in myChain has not returned from hostReady yet, the following is logged:

Chain myChain is handling hostReady call

Calling ConnectivityPlugins.onApplicationInitialized also notifies the correlator-integrated messaging for JMS, if enabled, that it is ready to receive events. It will then implicitly perform the JMS.onApplicationInitialized() call (see Using EPL to send and receive JMS messages). You should only call ConnectivityPlugins.onApplicationInitialized() once the application is ready to receive all incoming events, either from connectivity chains or JMS.

You can use the Diagnostic codec to view the messages being sent at any point in the connectivity chain. This is very useful for diagnosing problems, and for configuring message transformations using codecs such as the Mapper and Classifier codecs. For more information, see The Diagnostic codec connectivity plug-in for further information.

The samples/connectivity_plugin/application/genericsendreceive directory of your Apama installation includes a simple sample which provides an easy way to get started with sending and receiving messages to or from any connectivity plug-in.

The sample contains some simple event definitions called mypackage.MySampleInput and mypackage.MySampleOutput that can be used for input and output messages. These event definitions can be customized with additional fields as you wish.

In addition, the sample contains a monitor that subscribes to a specific transport channel and logs all events received from it, and also sends test events to a specific transport channel.

To use the sample, simply copy it into your Apama work directory or import it into Software AG Designer as an existing project. Then customize the channel (or channels) it is sending to/from to match the channel naming scheme specified in the documentation or configuration of the transport you are using (for example, um:MyChannelName for Universal Messaging). Finally, add and configure the connectivity plug-in you wish to use (see also Standard Connectivity Plug-ins). Depending on the transport and chain configuration you are using, you may also need to configure Mapper and/or Classifier codec rules in the YAML file (see also Codec Connectivity Plug-ins) to use the mypackage.MySampleInput and mypackage.MySampleOutput event definitions used by the sample.