Using Digital Event Services in Apama Applications

Software AG Digital Event Services is a messaging system for communicating between different Software AG products using events. Digital Event Services allows event definitions to be converted between a product's internal event or document definition to digital event types and vice versa, so participating products can share a set of event definitions. When you develop Apama applications that make use of Digital Event Services, the digital event type definitions are automatically translated to Apama event types. When digital events are sent to or received from Digital Event Services, they are converted to or from Apama events.

For details of the event mapping, see the .mon source file that is generated into the autogenerated node of your Apama project in Software AG Designer. Note that digital event types that contain nested events (or sequences of nested events) are converted to Apama event definitions that have an optional member (or sequence of optionals) for that event type. See the description of the optional type for more information. When digital events are converted to Apama events, fields of other types with no value set are set to the default value for that type (see also Default values for types).

Note:

In this release, it is not possible to turn your own Apama event types into digital event types. At the moment, digital event types can only be added to the system by other Software AG products (for example, webMethods Integration Server).

In this release, Apama does not support end-to-end reliable messaging with Digital Event Services. Using persistent delivery will not give you any supported reliability guarantees.

To use digital event types in your Apama application, proceed as follows:

1. Install and configure Software AG Digital Event Services. See the Digital Event Services documentation for detailed information.

2. Use Software AG Designer to add the Digital Event Services connectivity bundle to your Apama project. For detailed information, see Using the Digital Event Services connectivity bundle.

3. In the Apama Digital Event Types editor, select all digital event types that you want to use in your application. You use the digital event types just like ordinary Apama events. You can create digital events, create event expressions for them, set and get their contents, pass them around internally between monitors and contexts, and much more. See the above-mentioned topic for more information.

4. Edit the DESConnectivity.properties file to configure the Digital Event Services connectivity plug-in which defines the Apama connection to Digital Event Services. See the above-mentioned topic for more information.

As with all connectivity plug-ins, the EPL application is responsible for telling the system when it is ready to start receiving events with onApplicationInitialized. See also Sending and receiving events with connectivity plug-ins.

The following Apama actions on the digital event types support receiving digital events from and sending them to Digital Event Services:

Action	Description
subscribe()	This is a static action which behaves very much like monitor.subscribe (see also Subscribing to channels). It subscribes the context that calls it to events of that type from Digital Event Services.
unsubscribe()	This is a static action which behaves very much like monitor.unsubscribe. It unsubscribes the context from digital events of that type.
sendToDES()	This is a normal action, not a static action. It sends the event to Digital Event Services.

For example, you have a digital event type called pkg1.pkg2.MyEvent, with fields anInteger and aString on it. If you select this type in Software AG Designer, you are able to write EPL such as the following:

using com.softwareag.connectivity.ConnectivityPlugins;
using pkg1.pkg2.MyEvent;
...

ConnectivityPlugins.onApplicationInitialized();
MyEvent.subscribe(); // This context will now receive digital events
// of type 'pkg1.pkg2.MyEvent'

on all MyEvent() as e {
print "Got an event from DE: " + e.toString();
}

MyEvent e2 := new MyEvent;
e2.anInteger := 100;
e2.aString := "Hello world!";
e2.sendToDES(); // Sends this event out to Digital Event Services

There is one thing about digital events that is totally different from Apama events. Digital events of different types are not guaranteed to be received by Digital Event Services in the same order as they were sent. When you are sending Apama events as shown in the following example, then it is guaranteed that the destination context (ctx) can see the A and B events in the same order as they were sent.

If you are sending digital events as shown in the example below, any other product (or even Apama) that is receiving these events from Digital Event Services is guaranteed to see A(2) after A(1), and B(2) after B(1). These A and B events, however, might (or might not) be interleaved differently.