3.5. Processing Activity Events

You can use the Event Processor and supporting components directly within the Activity Collection mechanism or from nodes within an Event Processor Network. This section discusses Event Processors, Event Processor Network, Predicates and how you can define custom processors and predicates.

3.5.1. Configuring an Event Processor Network

3.5.1.1. Defining the Event Processor Network

An EPN (Event Processor Network) processes a stream of events through a network of linked nodes established to perform specific filtering, transformation or analysis tasks. You can define this network as an object model or specify it as a JSON representation for packaging in a suitable form, and subsequently de-serialized when deployed to the Runtime Governance server.
The following is an example of the JSON representation of an Event Processor Network. This example defines the out of the box Event Processor Network installed with the distribution: 
{
  "name" : "Overlord-RTGov-EPN",
  "version" : "1.0.0.Final",
  "subscriptions" : [ {
    "nodeName" : "SOAEvents",
    "subject" : "ActivityUnits"
  },
  {
    "nodeName" : "ServiceDefinitions",
    "subject" : "ActivityUnits"
  },
  {
    "nodeName" : "SituationsStore",
    "subject" : "Situations"
  } ],
  "nodes" : [
    {
      "name" : "SOAEvents",
      "sourceNodes" : [ ],
      "destinationSubjects" : [ "SOAEvents" ],
      "maxRetries" : 3,
      "retryInterval" : 0,
      "eventProcessor" : {
        "@class" : "org.overlord.rtgov.content.epn.SOAActivityTypeEventSplitter"
      },
      "predicate" : null,
      "notifications" : [ ]
    },{
      "name" : "ServiceDefinitions",
      "sourceNodes" : [ ],
      "destinationSubjects" : [ ],
      "maxRetries" : 3,
      "retryInterval" : 0,
      "eventProcessor" : {
        "@class" : "org.overlord.rtgov.content.epn.ServiceDefinitionProcessor"
      },
      "predicate" : null,
      "notifications" : [ {
        "type" : "Results",
        "subject" : "ServiceDefinitions"
      } ]
    },{
      "name" : "ServiceResponseTimes",
      "sourceNodes" : [ "ServiceDefinitions" ],
      "destinationSubjects" : [ "ServiceResponseTimes" ],
      "maxRetries" : 3,
      "retryInterval" : 0,
      "eventProcessor" : {
        "@class" : "org.overlord.rtgov.content.epn.ServiceResponseTimeProcessor"
      },
      "predicate" : null,
      "notifications" : [ {
        "type" : "Results",
        "subject" : "ServiceResponseTimes"
      } ]
    },{
      "name" : "SituationsStore",
      "maxRetries" : 3,
      "retryInterval" : 0,
      "eventProcessor" : {
        "@class" : "org.overlord.rtgov.ep.jpa.JPAEventProcessor",
        "entityManager" : "overlord-rtgov-epn-non-jta"
      }
    }
  ]
}

3.5.1.2. Event Processor Network Example

This example illustrates the configuration of a service associate with the event processor, as well as a predicate: 
{
  "name" : "AssessCreditPolicyEPN",
  "version" : "1",
  "subscriptions" : [ {
    "nodeName" : "AssessCredit",
    "subject" : "SOAEvents"
  } ],
  "nodes" : [
    {
      "name" : "AssessCredit",
      "sourceNodes" : [ ],
      "destinationSubjects" : [ ],
      "maxRetries" : 3,
      "retryInterval" : 0,
      "predicate" : {
        "@class" : "org.overlord.rtgov.ep.mvel.MVELPredicate",
        "expression" : "event.serviceProvider && !event.request && event.serviceType == \"{urn:switchyard-quickstart-demo:orders:0.1.0}OrderService\""
      },
      "eventProcessor" : {
        "@class" : "org.overlord.rtgov.ep.mvel.MVELEventProcessor",
        "script" : "AssessCredit.mvel",
        "services" : {
          "CacheManager" : {
            "@class" : "org.overlord.rtgov.common.infinispan.service.InfinispanCacheManager"
          }
        }
      }
    }
  ]
}
Here,

Table 3.16. Top Level Elements

Filed Description
name The name of the network.
subscriptions The list of subscriptions associated with the network.
nodes The nodes that form the connected graph within the network.
version The version of the network.
Subscriptions
The subscription element is used to define a subject that the network is interested in, and the name of the node to which the events from that subject should be routed. This decoupled subscription approach enables multiple networks to register their interest in events from the same subject. Multiple nodes within the same network can subscribe to the same subject. The fields associated with this component are:

Table 3.17. Fields Associated with Subscriptions

Field Description
subject The subject to subscribe to.
nodeName The name of the node within the network to route the events to.
This is a list of the subjects that are reserved for Red Hat JBoss Governance's use:

Table 3.18. Subjects Reserved for Governance

Subject Purpose
ActivityUnits This subject is used to publish events of the type org.overlord.rtgov.activity.model.ActivityUnit, produced when activity information is recorded with the Activity Server.
Node
This element is used to define a particular node in the graph that forms the network. The fields associated with this component are:

Table 3.19. Node Fields

Field Description
name The name of the node.
sourceNodes A list of node names that represent the source nodes, within the same network that this node receives its events from. Therefore, if this list is empty, it means that the node is a root node and should be the target of a subscription.
destinationSubjects A list of inter-EPN subjects to publish any resulting events to. These subjects are only of relevance to other networks.
maxRetries The maximum number of times an event should be retried, following a failure, before giving up on the event.
retryInterval The delay that should occur between retry attempts. This may not be supported in some environments.
eventProcessor Defines the details for the event processor implementation being used. At a minimum, the value for this field should define a @class property to specify the Java class name for the event process implementation to use. Another general field that can be configured is the map of services that can be used by the event processor. Depending upon which implementation is selected, the other fields within the value apply to the event processor implementation.
predicate This field is optional, but if specified, it defines a predicate implementation. As with the event processor, it must at a minimum define a @class field that specifies the Java class name for the implementation, with any additional fields be used to initialize the predicate implementation.
notifications A list of notifications. A notification entry defines its type and the notification subject upon which the information should be published. Unlike the destinationSubjects, which are subjects for inter-EPN communication, these notification subjects are the mechanism for distribution information out of the EPN capability, for presentation to end-users through various means.
The notify types field defines what type of notifications should be emitted from a node when processing an event. The notifications are the mechanism used by potentially interested applications to observe what information each node is processing, and the results they produce. The possible values for this field are:

Table 3.20. Notification Values

Field Description
Processed This type indicates that a notification should be created when an event is considered suitable for processing by the node. An event is suitable either if no predicate is defined, or if the predicate indicates the event is valid.
Results This type indicates that a notification should be created for any information produced as the result of the event processor processing the event.
Note
Notification is the mechanism for making information processed by the Event Processor Network accessible by interested parties. If a notification is not defined for a node, then it will only be used for internal processing, potentially supplying the processed event to other nodes in the network (or other networks, if destination subject(s) are specified).

3.5.1.3. Registering the Event Processor Network

The Event Processor Network is deployed within the JEE container as a WAR file with the following structure: 
warfile
|
|-META-INF
|    |- beans.xml
|
|-WEB-INF
|    |-classes
|    |    |-epn.json
|    |    |-<custom classes/resources>
|    |
|    |-lib
|       |-epn-loader-jee.jar
|       |-<additional libraries>
The epn.json file contains the JSON representation of the Event Processor Network configuration. The epn-loader-jee.jar acts as a bootstrapper to load and register the Event Processor Network. If custom predicates or event processors are defined, then the associated classes and resources can be defined in the WEB-INF/classes folder or within additional libraries located in the WEB-INF/lib folder. A maven pom.xml that creates this structure is shown below: 
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
        <modelVersion>4.0.0</modelVersion>
        <groupId>....</groupId>
        <artifactId>....</artifactId>
        <version>....</version>
        <packaging>war</packaging>
        <name>....</name>

        <properties>
                <rtgov.version>....</rtgov.version>
        </properties>

        <dependencies>
                <dependency>
                        <groupId>org.overlord.rtgov.event-processor-network</groupId>
                        <artifactId>epn-core</artifactId>
                        <version>${rtgov.version}</version>
                        <scope>provided</scope>
                </dependency>
                <dependency>
                        <groupId>org.overlord.rtgov.event-processor-network</groupId>
                        <artifactId>epn-loader-jee</artifactId>
                        <version>${rtgov.version}</version>
                </dependency>
                ....
        </dependencies>

</project>
If you are deploying in JBoss Application Server, then you also need to include the following fragment to define the dependency on the core Runtime Governance modules: 
.....
        <build>
                <finalName>slamonitor-epn</finalName>
                <plugins>
                        <plugin>
                                <artifactId>maven-war-plugin</artifactId>
                                <configuration>
                                        <failOnMissingWebXml>false</failOnMissingWebXml>
                                        <archive>
                                                <manifestEntries>
                                                        <Dependencies>deployment.overlord-rtgov.war</Dependencies>
                                                </manifestEntries>
                                        </archive>
                                </configuration>
                        </plugin>
                </plugins>
        </build>
        .....

3.5.1.4. Supporting Multiple Versions of the Event Processor Network

Event Processor Networks define a version number that can be used to keep track of the evolution of changes in a network. When a network is deployed to a container, and used to process events, a newer version of the network can be deployed along side the existing version to ensure there is continuity in the processing of the event stream. New events presented to the network are processed by the most recent version, while events still being processed by a particular version of the network, continue to be processed by the same version, thus ensuring that changes to the internal structure of the network do not impact events that are mid-way through being processed by the network. You can determine when an older version of the network last processed an event, and therefore when an older version has been inactive for a suitable amount of time, it can be unregistered.

3.5.2. Event Processor Implementations

3.5.2.1. Introduction

SwitchYard provides the following out of the box Event Processor implementations:
  • Drools Event Processor
  • JPA Event Processor
  • Mail Event Processor
  • MVEL Event Processor
Details about these out of the box implementations and how you can configure custom event processors are described in this section.

3.5.2.2. Drools Event Processor

The Drools Event Processor implementation ( org.overlord.rtgov.ep.drools.DroolsEventProcessor ) enables events to be processed by a Complex Event Processing (CEP) rule. This implementation defines the following additional fields:

Table 3.21. Drools Event Processor

Field Description
ruleName The name of the rule, used to locate the rule definition in a file called <ruleName>.drl
Here is an example of such a rule: 
import org.overlord.rtgov.activity.model.soa.RequestReceived
import org.overlord.rtgov.activity.model.soa.ResponseSent

global org.overlord.rtgov.ep.EPContext epc

declare RequestReceived
    @role( event )
    @timestamp( timestamp )
    @expires( 2m20s )
end

declare ResponseSent
    @role( event )
    @timestamp( timestamp )
    @expires( 2m20s )
end

rule "correlate request and response"
when
    $req : RequestReceived( $id : messageId ) from entry-point "Purchasing"
    $resp : ResponseSent( replyToId == $id, this after[0,2m20s] $req )  from entry-point "Purchasing"
then

    epc.logInfo("REQUEST: "+$req+" RESPONSE: "+$resp);

    java.util.Properties props=new java.util.Properties();
    props.put("requestId", $req.getMessageId());
    props.put("responseId", $resp.getMessageId());

    long responseTime=$resp.getTimestamp()-$req.getTimestamp();

    epc.logDebug("CORRELATION on id '"+$id+"' response time "+responseTime);

    props.put("responseTime", responseTime);

    epc.handle(props);

end
This is an example of a rule used to correlate request and response events. When a correlation is found, then a ResponseTime object is created and forwarded to the Event Processor Network for further processing using the handle method. The source of the events into the rule are called entry points, where the name relates to the source node or subject that supplies the events. The rule has access to external capabilities through the EPContext , which is defined in the statements such as: 
global org.overlord.rtgov.ep.EPContext epc
EPContext is used at the end of the above example to handle the result of the event processing (that is, to forward a derived event back into the network.
If an error occurs, that requires the event to be retried (within the Event Processor Network), or the business transaction blocked (when used as a synchronous policy), then the rule can either throw an exception or return the exception as the result using the handle() method.
Warning
Temporal rules do not currently work in a clustered environment. This is because correlation between events occurs in working memory, which is not shared across servers. Therefore, for the correlation to work, all relevant events must be received by a single server.

3.5.2.3. JPA Event Processor

A JPA based Event Processor implementation (org.overlord.rtgov.ep.jpa.JPAEventProcessor) enables events to be persisted. This implementation defines the following additional fields:

Table 3.22. Additional Fields for JPA Event Processor Implementation

Field Description
entityManager The name of the entity manager to be used.

3.5.2.4. Mail Event Processor

A mail based Event Processor implementation ( org.overlord.rtgov.ep.mail.MailEventProcessor ) enables events to be transformed and sent as an email. This implementation defines the following additional fields:

Table 3.23. Additional Fields for Mail Event Processor Implementation

Field Description
from The from email address.
to The list of to email addresses.
subjectScript The location of the MVEL script, which may be relative to the classpath, used to define the email subject.
contentScript The location of the MVEL script, which may be relative to the classpath, used to define the email content.
contentType The optional type of the email content. By default it will be "text/plain".
jndiName The optional JNDI name locating the JavaMail session.

3.5.2.5. MVEL Event Processor

A MVEL based Event Processor implementation ( org.overlord.rtgov.ep.mvel.MVELEventProcessor ) enables events to be processed by a MVEL script. This implementation defines the following additional fields:

Table 3.24. MVEL Event Processor Fields

Field Description
script The location of the MVEL script, which may be relative to the classpath.
The script will have access to the following variables:

Table 3.25. Script Variables

Variable Description
source The name of the source node or subject upon which the event was received.
event The event to be processed.
retriesLeft The number of retries remaining.
epc The EP context ( org.overlord.rtgov.ep.EPContext ), providing some utility functions for use by the script, including the handle method for pushing the result back into the network.
If an error occurs, that requires the event to be retried (within the Event Processor Network), or the business transaction blocked (when used as a synchronous policy), then the script can return the exception as the result using the handle() method.

3.5.2.6. Creating Custom Event Processors

The org.overlord.rtgov.ep.EventProcessor abstract class is responsible for processing an event routed to a particular node within the Event Processor Network. To create a custom implementation, derive a class from the EventProcessor abstract class. This class provides the following methods:

Table 3.26. Custom Event Processors

Method Description
java.util.Map<String,Service> getServices() This method returns the map of services available to the Event Processor.
void setServices(java.util.Map<String,Service> services) This method sets the map of services available to the Event Processor.
void init() This method is called when the event processor is first initialized as part of the Event Processor Network. A custom implementation does not need to override this method if not required.
Serializable process(String source, Serializable event, int retriesLeft) throws Exception This method processes the supplied event, indicating the source of the event and how many retries are left (so that suitable error handling can be performed in no more retries remain.

3.5.2.7. Support Service by Cache Manager

This section describes the Cache Manager that enables event processors to store and retrieve information in named caches. The Cache Manager provides the following methods:

Table 3.27. API

Method Description
<K,V> Map<K,V> getCache(String name) This method returns the cache associated with the supplied name. If the cache does not exist, then a null will be returned.
boolean lock(String cacheName, Object key) This method locks the item, associated with the supplied key, in the named cache.

Table 3.28. Implementations

Implementation Class Name Description
Infinispan org.overlord.rtgov.common.infinispan.service.InfinispanCacheManager This class provides an implementation based on Infinispan. It has a property called container which represents the optional JNDI name for the infinispan container defined in the standalone-full.xml or standalone-full-ha.xml file.
The Infinispan Container is obtained in one of these three possible ways:
  • If the container is explicitly defined, then it is used.
  • If the container is not defined, then a default container is obtained from the $JBOSS_HOME/standalone/configuration/overlord-rtgov.properties file for the infinispan.container property.
  • if no default container is defined, then a default cache manager is created.

3.5.2.8. Creating Custom Services

The org.overlord.rtgov.common.service.Service abstract class is used to provide services for use by event processors, such as a CacheManager. To create a custom implementation, derive a class from the Service abstract class. This class provides the following methods:

Table 3.29. Custom Service Methods

Method Description
void init() This method is called when the service is first initialized. A custom implementation does not need to override this method if it is not required.

3.5.3. Predicates

3.5.3.1. MVEL Predicate

An MVEL based Predicate implementation (org.overlord.rtgov.ep.mvel.MVELPredicate) enables events to be evaluated by a MVEL expression or script. This implementation defines the following additional fields:

Table 3.30. MVEL Predicate

Field Description
expression The MVEL expression used to evaluate the event.
script The location of the MVEL script, which may be relative to the classpath.
Warning
You can define only one of these fields in your implementation.

3.5.3.2. Creating Custom Predicates

The org.overlord.rtgov.ep.Predicate abstract class is responsible for determining whether an event is suitable to be processed by a particular node within the Event Processor Network. To create a custom implementation, derive a class from the Predicate abstract class. This class provides the following methods:

Table 3.31. Methods of Predicate Class

Method Description
void init() This method is called when the predicate is first initialized as part of the Event Processor Network. A custom implementation does not need to override this method if not required.
boolean evaluate(Object event) This method determines whether the supplied event must be processed by the node.

3.5.4. Packaging

The custom predicate or event processor implementations must be available to the classloader when an Event Processor Network or Activity Validator referencing the implementations is loaded. You can achieve this either by packaging the implementations with the Event Processor Network or Activity Validator configuration, or by installing them in a common location used by the container in which the Event Processor Network or Activity Validator is being loaded.