Runtime Governance: User Guide

To use Elasticsearch as the Activity and Situation Store implementation, the following property values need to be defined:

ActivityStore.class=org.overlord.rtgov.activity.store.elasticsearch.ElasticsearchActivityStore
SituationStore.class=org.overlord.rtgov.analytics.situation.store.elasticsearch.ElasticsearchSituationStore

with the additional support properties:

To use a SQL database as the Activity and Situation Store implementation, the following property values need to be defined:

with the additional support properties:

The samples/ordermgmt folder contains examples related to an Order Management system implemented using a SwitchYard application.

The samples/ordermgmt/app folder contains the switchyard application, with some additional interceptors to execute policies synchronously (see Activity Validators section for more information, and the Synchronous Policy quickstart more a specific example of its use).

The samples/ordermgmt/epn folder contains an Event Processor Network (see later section for details) that is used to convert switchyard application exceptions into "Situations", which is a form of alert used by the Runtime Governance platform.

The samples/ordermgmt/ip folder contains an Information Processor (see later sectoin for details) that is used to extract additional information from message payloads, that will be useful when analysing the activity events.

The samples/policy/sync folder contains a policy that is invoked synchronously - it determines whether a user has invoked the service more than once every two seconds, and if so, blocks the service invocation.

The samples/policy/async folder contains a policy for asynchronously calculating the debt associated with a customer, and suspending their account if it goes above a defined level. The suspended status of the customer is checked when they next invoke the service, and the service invocation blocked if they have been suspended.

The samples/sla/epn folder contains a policy for determining whether a Service Level Agreement has been violated, and if so, reported as a Situation.

The samples/sla/monitor folder contains a webapp that directly integrates with the RTGov components.

To install an OSGi application to provide a simple order management capabilty, with an Event Processor Network to convert exceptions into Situations, run the following command from the fuse console:

features:install rtgov-samples-ordermgmt-epn

To install a policy that will check for SLA violations, run the following command from the fuse console:

features:install rtgov-samples-sla

To install a policy that will be evaluated immediately, to prevent a customer from invoking a service more than once within two seconds, run the following comand from the fuse console:

features:install rtgov-samples-policy-sync

To install a policy that will evaluate a customer’s debt level, and suspend their account if it becomes too high, run the following comand from the fuse console:

features:install rtgov-samples-policy-async

This graph displays response time information that matches any defined filter. Initially the only filter that is applied is a default time frame showing information over the last 24 hours (see following section on Changing the Time Frame and Refresh Cycle).

All response time information will be shown in the same (green) colour. This enables a general indication of performance to be obtained, but to identify specific issues it will be necessary to isolate response times of interest. This can be achieved using "Filtering by query" to only show response times within a particular range.

It is also possible to colour code response time information associated with particular subsets of the information (e.g. for particular service types, or customers, etc). See Segmenting information by query section for more information.

This table shows the list of services. Each service is listed with the number of invocations (count) and actions that can be used to focus or exclude the particular service from the information being viewed.

By default, the services listed in the table are related to public services. However if a service is marked as internal, then they will be excluded using the following filter:

To include the internal services in the service table, simply disable this filter by unchecking the filter.

This pie chart shows the distribution of faults that occur within the filtered response time information being viewed.

The segment labels mean:

Selecting a region from the pie chart will further focus the dashboard on response time information associated with that catagory of fault. To cancel the filter, select the "FILTERING" green tab at the top of the page, and either disable or remove the entry matching the fault filter.

This bar charts shows the distribution of the response time information over time, grouped by a specified time interval (initially 1 minute).

When subsets of information are defined, based on pinned queries, it is possible to get more interesting results based on colour coded regions. For example, if separate queries are used to represent response times associated with different service types, then the bars will be colour coded to show how much activity occurred on each of the service types.

This pie chart is used to decompose the activities based on the operations that were performed, subject to any other filters that may have been applied.

It is also possible to create an additional filter on the currently viewed information, based on a particular operation, by selecting the operation of interest’s segment within the pie chart. To cancel the filter, simply select the "FILTERING" green tab at the top of the page, and either disable or remove the entry matching the operation filter.

This section provides a list of the most recent response time information. The columns provide a small selection of fields from the response time events, with a list of the available fields as checkboxes down the left hand side. This enables the user to select additional fields of interest.

When a row is selected, it will expand to show the complete set of fields from the response time event, with some action icons next to each value. If the user selects the magnifying glass, then the dashboard will be additional focused on response time information associated with that field value, and similarly selecting the no entry sign will exclude information with that field value.

As mentioned previously, cancelling a particular filter can be achieved by selecting the "FILTERING" green tab at the top of the page, and either disable or remove the entry matching the field filter.

To collect activity events from a SwitchYard environment, simply install either the full server (if the execution and governance server are running co-located) or the client installation profile (if reporting events to another server).

To collect activity events from an OSGi application, a proxy can be used to intercept inbound and outbound invocations on a service, and report the activity to an embedded activity collector within the OSGi container. These proxies can be wired into an OSGi application using blueprint, e.g.

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://www.osgi.org/xmlns/blueprint/v1.0.0 http://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd">

    <service interface="org.overlord.rtgov.quickstarts.demos.ordermgmt.orderservice.OrderService"
    						ref="orderServiceProxy" />

    <bean id="orderServiceProxy" class="org.overlord.rtgov.client.ActivityProxyHelper"
    			factory-method="createServiceProxy" >
    	<argument value="org.overlord.rtgov.quickstarts.demos.ordermgmt.orderservice.OrderService" />
    	<argument ref="orderServiceBean" />
   	</bean>

    <bean id="orderServiceBean" class="org.overlord.rtgov.quickstarts.demos.ordermgmt.orderservice.OrderServiceBean" >
       	<property name="inventoryService" ref="inventoryServiceProxy"/>
       	<property name="logisticsService" ref="logisticsServiceProxy"/>
    </bean>

    <bean id="inventoryServiceProxy" class="org.overlord.rtgov.client.ActivityProxyHelper"
    			factory-method="createClientProxy" >
    	<argument value="org.overlord.rtgov.quickstarts.demos.ordermgmt.inventoryservice.InventoryService" />
    	<argument ref="orderServiceBean" />
    	<argument ref="inventoryServiceBean" />
   	</bean>

    <bean id="logisticsServiceProxy" class="org.overlord.rtgov.client.ActivityProxyHelper"
    			factory-method="createClientProxy" >
    	<argument value="org.overlord.rtgov.quickstarts.demos.ordermgmt.logisticsservice.LogisticsService" />
    	<argument ref="orderServiceBean" />
    	<argument ref="logisticsServiceBean" />
   	</bean>

    <reference id="inventoryServiceBean"
               interface="org.overlord.rtgov.quickstarts.demos.ordermgmt.inventoryservice.InventoryService">
    </reference>

    <reference id="logisticsServiceBean"
               interface="org.overlord.rtgov.quickstarts.demos.ordermgmt.logisticsservice.LogisticsService">
    </reference>

</blueprint>

The service interface is associated with a bean representing the service proxy, created using the createServiceProxy static factory method on the class org.overlord.rtgov.client.ActivityProxyHelper.

Similarly, the outbound relationships from the service to other OSGi components are established via a client proxy, using the createClientProxy static factory method on the org.overlord.rtgov.client.ActivityProxyHelper class.

The Information Processor can be defined as an object model or specified as a JSON representation for packaging in a suitable form, and subsequently de-serialized when deployed to the governed execution environment.

The following is an example of the JSON representation of a list of Information Processors. This particular example accompanies the Order Management sample:

[{
	"name":"OrderManagementIP",
	"version":"1",
	"typeProcessors":{
		"{urn:switchyard-quickstart-demo:orders:1.0}submitOrder":{
			"contexts":[{
				"type":"Conversation",
				"evaluator":{
					"type":"xpath",
					"expression":"order/orderId"
				}
			}],
			"properties":[{
				"name":"customer",
				"evaluator":{
					"type":"xpath",
					"expression":"order/customer"
				}
			},{
				"name":"item",
				"evaluator":{
					"type":"xpath",
					"expression":"order/itemId"
				}
			}]
		},
		"{urn:switchyard-quickstart-demo:orders:1.0}submitOrderResponse":{
			"contexts":[{
				"type":"Conversation",
				"evaluator":{
					"type":"xpath",
					"expression":"orderAck/orderId"
				}
			}],
			"properties":[{
				"name":"customer",
				"evaluator":{
					"type":"xpath",
					"expression":"orderAck/customer"
				}
			},{
				"name":"total",
				"evaluator":{
					"type":"xpath",
					"expression":"orderAck/total"
				}
			}]
		},
		"java:org.switchyard.quickstarts.demos.orders.Order":{
			"contexts":[{
				"type":"Conversation",
				"evaluator":{
					"type":"mvel",
					"expression":"orderId"
				}
			}],
			"properties":[{
				"name":"customer",
				"evaluator":{
					"type":"mvel",
					"expression":"customer"
				}
			},{
				"name":"itemId",
				"evaluator":{
					"type":"mvel",
					"expression":"itemId"
				}
			}]
		},
		"java:org.switchyard.quickstarts.demos.orders.OrderAck":{
			"contexts":[{
				"type":"Conversation",
				"evaluator":{
					"type":"mvel",
					"expression":"orderId"
				}
			}],
			"properties":[{
				"name":"customer",
				"evaluator":{
					"type":"mvel",
					"expression":"customer"
				}
			},{
				"name":"total",
				"evaluator":{
					"type":"mvel",
					"expression":"total"
				}
			}]
		},
		"{urn:switchyard-quickstart-demo:orders:1.0}makePayment":{
			"properties":[{
				"name":"customer",
				"evaluator":{
					"type":"xpath",
					"expression":"payment/customer"
				}
			},{
				"name":"amount",
				"evaluator":{
					"type":"xpath",
					"expression":"payment/amount"
				}
			}]
		},
		"{urn:switchyard-quickstart-demo:orders:1.0}makePaymentResponse":{
			"properties":[{
				"name":"customer",
				"evaluator":{
					"type":"xpath",
					"expression":"receipt/customer"
				}
			},{
				"name":"amount",
				"evaluator":{
					"type":"xpath",
					"expression":"receipt/amount"
				}
			}]
		},
		"java:org.switchyard.quickstarts.demos.orders.Receipt":{
			"properties":[{
				"name":"customer",
				"evaluator":{
					"type":"mvel",
					"expression":"customer"
				}
			},{
				"name":"amount",
				"evaluator":{
					"type":"mvel",
					"expression":"amount"
				}
			}]
		},
		"java:org.switchyard.quickstarts.demos.orders.ItemNotFoundException":{
			"script":{
				"type":"mvel",
				"expression":"activity.fault = \"ItemNotFound\""
			}
		}
	}
}]

This example illustrates the configuration of a single Information Processor with the top level elements:

When comparing versions, for example when determining whether a newly deployed Information Processor has a higher version than an existing one with the same name, then initially the versions will be compared as numeric values. If either are not numeric, then they will be compared using dot format, with each field being compared first as numeric values, and if not based on lexical comparison. If both fields don’t have a dot, then they will just be compared lexically.

Type Processor

The type processor element is associated with a particular information type (i.e. as its key). The fields associated with this component are:

Context Evaluator

The fields associated with the Context Evaluator component are:

The context types represent different ways in which the activity events can be related to each other or to a logical grouping (e.g. business transaction). Not all activity events need to be associated directly with a global business transaction id. They can be indirectly associated based on transitive correlation - e.g. activity 1 is associated with the global business transaction id, activity 2 is associated with activity 1 by a message context type, and activity 3 is associated with activity 2 based on an endpoint correlation id. All three activity events will be collectively correlated to the business transaction id.

An explanation of the different context types is,

Property Evaluator

The fields associated with the Property Evaluator component are:

Expression Evaluator

In the context and property evaluator components, they reference an expression evaluator that is used to derive their value. The expression evaluator has the following fields:

These expressions operate on the information being processed, to return a string value to be applied to the appropriate context or property.

Script

The script field of the Type Processor has the following fields:

The MVEL script evaluator is supplied two variables for its use:

An example of how this script can be used is shown in the example above, associated with the ItemNotFoundException. In this case, the message on the wire does not carry the fault name, so the information processor is used to set the fault field on the activity event.

Transformer

The transformer field of the Type Processor has the following fields:

The serialize transformer can take one optional additional boolean field includeHeaders (with default value false). This transformer simply attempts to convert the representation of the information into a textual form for inclusion in the activity event. So this transformer type can be used where the complete information content is required. If the optional includeHeaders field is specified as true, then any header values that accompany the message that are represented as either String or DOM, will be serialized in an internal property, which can then be used by tooling (e.g. the resubmission capability in the RTGov UI).

The mvel transformer takes the following additional fields:

The MVEL transformer script is supplied the following variable for its use:

The MVEL transformer is supplied the following variable for its use:

For example, to include the content of the submitOrder message:

	"typeProcessors":{
		"{urn:switchyard-quickstart-demo:orders:1.0}submitOrder":{
			....
			"transformer":{
				"type":"serialize"
			}
		},

JEE Container

The Information Processors are deployed within the JEE container as a WAR file with the following structure:

warfile
|
|-META-INF
|    |- beans.xml
|
|-WEB-INF
|    |-classes
|    |    |-ip.json
|    |    |-<custom classes/resources>
|    |
|    |-lib
|       |-ip-loader-jee.jar
|       |-<additional libraries>

The ip.json file contains the JSON representation of the Information Processor configuration.

The ip-loader-jee.jar acts as a bootstrapper to load and register the Information Processors.

If custom classes 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 will create this structure is:

<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.activity-management</groupId>
			<artifactId>activity</artifactId>
			<version>${rtgov.version}</version>
			<scope>provided</scope>
		</dependency>
		<dependency>
			<groupId>org.overlord.rtgov.activity-management</groupId>
			<artifactId>ip-loader-jee</artifactId>
			<version>${rtgov.version}</version>
		</dependency>
		....
	</dependencies>

</project>

If deploying in JBoss Application Server, then the following fragment also needs to be included, to define the dependency on the core Overlord Runtime Governance modules:

.....
	<build>
		<finalName>....</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>
	.....

OSGi Container

The Information Processors are deployed within the OSGi container as a JAR file with the following structure:

jarfile
|
|-META-INF
|    |- MANIFEST.MF
|
|-ip.json
|-ip-loader-osgi.jar
|-<custom classes/resources>
|-<additional libraries>

The ip.json file contains the JSON representation of the Information Processor configuration.

The ip-loader-osgi.jar acts as a bootstrapper to load and register the Information Processors.

If custom classes are defined, then any associated classes, resources and additional libraries are located in the top level folder.

A maven pom.xml that will create this structure is:

<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.activity-management</groupId>
			<artifactId>activity</artifactId>
			<version>${rtgov.version}</version>
			<scope>provided</scope>
		</dependency>
		<dependency>
			<groupId>org.overlord.rtgov.activity-management</groupId>
			<artifactId>ip-loader-osgi</artifactId>
			<version>${rtgov.version}</version>
		</dependency>
		....
	</dependencies>

	<build>
		<finalName>....</finalName>
		<resources>
			<resource>
				<directory>src/main/resources</directory>
				<filtering>true</filtering>
			</resource>
		</resources>
		<plugins>
			<plugin>
				<groupId>org.apache.felix</groupId>
				<artifactId>maven-bundle-plugin</artifactId>
 				<extensions>true</extensions>
				<configuration>
					<instructions>
						<Bundle-SymbolicName>${project.artifactId}</Bundle-SymbolicName>
						<Bundle-Version>${project.version}</Bundle-Version>
						<Bundle-Activator>org.overlord.rtgov.activity.processor.loader.osgi.IPActivator</Bundle-Activator>
						<Import-Package>
							!javax.inject.*,!javax.enterprise.*,!javax.persistence.*,
                            ....,
							*
						</Import-Package>
						<Embed-Dependency>*;scope=compile|runtime</Embed-Dependency>
					</instructions>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

The Activity Validator can be defined as an object model or specified as a JSON representation for packaging in a suitable form, and subsequently de-serialized when deployed to the governed execution environment.

The following is an example of the JSON representation of a list of Activity Validators. This particular example is from the synchronous policy sample:

[{
  "name" : "RestrictUsage",
  "version" : "1",
  "predicate" : {
    "@class" : "org.overlord.rtgov.ep.mvel.MVELPredicate",
    "expression" : "event instanceof org.overlord.rtgov.activity.model.soa.RequestReceived && event.serviceType == \"{urn:switchyard-quickstart-demo:orders:0.1.0}OrderService\""
  },
  "eventProcessor" : {
    "@class" : "org.overlord.rtgov.ep.mvel.MVELEventProcessor",
    "script" : "VerifyLastUsage.mvel",
    "services" : {
      "CacheManager" : {
        "@class" : "org.overlord.rtgov.common.infinispan.service.InfinispanCacheManager"
      }
    }
  }
}]

This example illustrates the configuration of a single Activity Validator with the top level elements:

When comparing versions, for example when determining whether a newly deployed Activity Validator has a higher version than an existing one with the same name, then initially the versions will be compared as numeric values. If either are not numeric, then they will be compared using dot format, with each field being compared first as numeric values, and if not based on lexical comparison. If both fields don’t have a dot, then they will just be compared lexically.

JEE Container

The Activity Validators are deployed within the JEE container as a WAR file with the following structure:

warfile
|
|-META-INF
|    |- beans.xml
|
|-WEB-INF
|    |-classes
|    |    |-av.json
|    |    |-<custom classes/resources>
|    |
|    |-lib
|       |-av-loader-jee.jar
|       |-<additional libraries>

The av.json file contains the JSON representation of the Activity Validator configuration.

The av-loader-jee.jar acts as a bootstrapper to load and register the Activity Validators.

If custom classes 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 will create this structure is:

<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.activity-management</groupId>
			<artifactId>activity</artifactId>
			<version>${rtgov.version}</version>
			<scope>provided</scope>
		</dependency>
		<dependency>
			<groupId>org.overlord.rtgov.activity-management</groupId>
			<artifactId>av-loader-jee</artifactId>
			<version>${rtgov.version}</version>
		</dependency>
		....
	</dependencies>

</project>

If deploying in JBoss Application Server, then the following fragment also needs to be included, to define the dependency on the core Overlord Runtime Governance modules:

.....
	<build>
		<finalName>....</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>
	.....

OSGi Container

The Activity Validators are deployed within the OSGi container as a JAR file with the following structure:

jarfile
|
|-META-INF
|    |- MANIFEST.MF
|
|-av.json
|-av-loader-osgi.jar
|-<custom classes/resources>
|-<additional libraries>

The av.json file contains the JSON representation of the Activity Validator configuration.

The av-loader-osgi.jar acts as a bootstrapper to load and register the Activity Validators.

If custom classes are defined, then any associated classes, resources and additional libraries can be located in the top level folder.

A maven pom.xml that will create this structure is:

<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.activity-management</groupId>
			<artifactId>activity</artifactId>
			<version>${rtgov.version}</version>
			<scope>provided</scope>
		</dependency>
		<dependency>
			<groupId>org.overlord.rtgov.activity-management</groupId>
			<artifactId>av-loader-osgi</artifactId>
			<version>${rtgov.version}</version>
		</dependency>
		....
	</dependencies>

	<build>
		<finalName>....</finalName>
		<resources>
			<resource>
				<directory>src/main/resources</directory>
				<filtering>true</filtering>
			</resource>
		</resources>
		<plugins>
			<plugin>
				<groupId>org.apache.felix</groupId>
				<artifactId>maven-bundle-plugin</artifactId>
 				<extensions>true</extensions>
				<configuration>
					<instructions>
						<Bundle-SymbolicName>${project.artifactId}</Bundle-SymbolicName>
						<Bundle-Version>${project.version}</Bundle-Version>
						<Bundle-Activator>org.overlord.rtgov.activity.validator.loader.osgi.AVActivator</Bundle-Activator>
						<Import-Package>
							!javax.inject.*,!javax.enterprise.*,!javax.persistence.*,
                            .....;
							*
						</Import-Package>
						<Embed-Dependency>*;scope=compile|runtime</Embed-Dependency>
					</instructions>
				</configuration>
			</plugin>
		</plugins>
	</build>

</project>

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. Equally multiple nodes within the same network could subscribe to the same subject.

The fields associated with this component are:

Reserved subjects

This is a list of the subjects that are reserved for Overlord’s use:

This element is used to define a particular node in the graph that forms the network, and has the following fields:

Notify Types

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:

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 EPN configuration.

The epn-loader-jee.jar acts as a bootstrapper to load and register the Event Processor Network.

If custom predicates and/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 will create this structure is:

<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 deploying in JBoss Application Server, then the following fragment also needs to be included, to define the dependency on the core Overlord Runtime Governance modules:

.....
	<build>
		<finalName>slamonitor-epn</finalName>
		<resources>
			<resource>
				<directory>src/main/resources</directory>
				<filtering>true</filtering>
			</resource>
		</resources>
		<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>
	.....

The Event Processor Network is deployed within the OSGi container as a JAR file with the following structure:

jarfile
|
|-META-INF
|    |- MANIFEST.MF
|
|-epn.json
|-epn-loader-osgi.jar
|-<custom classes/resources>
|-<additional libraries>

The MANIFEST.MF file is important, as it contains the OSGi metadata required for the container to understand the contents and imported packages.

The epn.json file contains the JSON representation of the EPN configuration.

The epn-loader-osgi.jar acts as a bootstrapper to load and register the Event Processor Network.

If custom predicates and/or event processors are defined, then the associated classes, resources and additional libraries can be located in the top level folder.

A maven pom.xml that will create this structure is:

<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-osgi</artifactId>
			<version>${rtgov.version}</version>
		</dependency>
		....
	</dependencies>

	<build>
		<finalName>....</finalName>
		<resources>
			<resource>
				<directory>src/main/resources</directory>
				<filtering>true</filtering>
			</resource>
		</resources>
		<plugins>
			<plugin>
				<groupId>org.apache.felix</groupId>
				<artifactId>maven-bundle-plugin</artifactId>
 				<extensions>true</extensions>
				<configuration>
					<instructions>
						<Bundle-SymbolicName>${project.artifactId}</Bundle-SymbolicName>
						<Bundle-Version>${project.version}</Bundle-Version>
						<Bundle-Activator>org.overlord.rtgov.epn.loader.osgi.EPNActivator</Bundle-Activator>
						<Import-Package>
							!javax.inject.*,!javax.enterprise.*,!javax.persistence.*,
                            ....,
							*
						</Import-Package>
						<Embed-Dependency>*;scope=compile|runtime</Embed-Dependency>
					</instructions>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

Description

The purpose of the Cache Manager service is to enable event processors to store and retrieve information in named caches.

API

Implementations

Infinispan

Class name: org.overlord.rtgov.common.infinispan.service.InfinispanCacheManager

This class provides an implementation based on Infinispan. The properties for this class are:

The container will be obtained in three possible ways.

(a) if the container is explicitly defined, then it will be used

(b) if the container is not defined, then a default container will be obtained from the $JBOSS_HOME/standalone/configuration/overlord-rtgov.properties file for the infinispan.container property.

(c) if no default container is defined, then a default cache manager will be created.

Aggregation

The aggregation script is used to (as the name suggests) aggregate information being provided by the source, before being applied to the collection. The values available to the MVEL script are:

The aggregated result will be returned from the script.

Scheduled

The scheduled script is used to perform regular tasks on the active collection, independent of any information being applied to the collection. The values available to the MVEL script are:

Maintenance

The maintenance script is used to manage how new information presented to the source is applied to the active collection. If no script is defined, then the information will be inserted by default. The values available to the MVEL script are:

An example script, showing how these variables can be used is:

int maxSnapshots=acs.properties.get("maxSnapshots");

snapshots = variables.get("snapshots");

if (snapshots == null) {
	snapshots = new java.util.ArrayList();
	variables.put("snapshots", snapshots);
}

// Update the current snapshot
currentSnapshot = variables.get("currentSnapshot");

if (currentSnapshot == null) {
	currentSnapshot = new java.util.HashMap();
}

snapshots.add(new java.util.HashMap(currentSnapshot));

currentSnapshot.clear();

// Remove any snapshots above the number configured
while (snapshots.size() > maxSnapshots) {
	snapshot = snapshots.remove(0);
}

// Merge snapshots
merged = org.overlord.rtgov.analytics.util.ServiceDefinitionUtil.mergeSnapshots(snapshots);

// Update existing, and remove definitions no longer relevant
foreach (entry : acs.activeCollection) {
	org.overlord.rtgov.analytics.service.ServiceDefinition sd=null;

	if (merged.containsKey(entry.key)) {
		acs.update(entry.key, merged.get(entry.key));
	} else {
		acs.remove(entry.key, entry.value);
	}

	merged.remove(entry.key);
}

// Add new definitions
for (key : merged.keySet()) {
	acs.insert(key, merged.get(key));
}

This example shows the script accessing the Active Collection Source and its properties, as well as accessing (and updating) the variables cache associated with the source.

The derived element defines a list of derived active collection definitions that will be instantiated with the active collection.

The fields associated with this component are:

The following properties can be defined:

The activeChangeListeners element defines a list of Active Change Listener implementations that will be instantiated and registered with the active collection.

The fields associated with this component are:

The remaining attributes in the example above will be discussed in a subsequent section related to reporting results via JMX notifications.

The factory element defines an Active Collection Factory implementation that will be used to create the active collection.

The fields associated with this component are:

The current list of factory implementations are defined below.

Infinispan

The fields associated with the org.overlord.rtgov.active.collection.infinispan.InfinispanActiveCollectionFactory component are:

The Active Collection Source is deployed within the JEE container as a WAR file with the following structure:

warfile
|
|-META-INF
|    |- beans.xml
|
|-WEB-INF
|    |-classes
|    |    |-acs.json
|    |    |-<custom classes/resources>
|    |
|    |-lib
|       |-acs-loader-jee.jar
|       |-<additional libraries>

The acs.json file contains the JSON representation of the Active Collection Source configuration.

The acs-loader-jee.jar acts as a bootstrapper to load and register the Active Collection Source.

If custom active collection source and/or active change listeners 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 will create this structure is:

<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.active-queries</groupId>
			<artifactId>active-collection</artifactId>
			<version>${rtgov.version}</version>
			<scope>provided</scope>
		</dependency>
		<dependency>
			<groupId>org.overlord.rtgov.active-queries</groupId>
			<artifactId>acs-loader-jee</artifactId>
			<version>${rtgov.version}</version>
		</dependency>
		....
	</dependencies>

</project>

If deploying in JBoss Application Server, then the following fragment also needs to be included, to define the dependency on the core Overlord rtgov modules:

.....
	<build>
		<finalName>....</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>
	.....

The Active Collection Source is deployed within the OSGi container as a JAR file with the following structure:

jarfile
|
|-META-INF
|    |- beans.xml
|
|-acs.json
|-acs-loader-osgi.jar
|-<custom classes/resources>
|-<additional libraries>

The acs.json file contains the JSON representation of the Active Collection Source configuration.

The acs-loader-osgi.jar acts as a bootstrapper to load and register the Active Collection Source.

If custom active collection source and/or active change listeners are defined, then the associated classes, resources and additional libraries can be located in the top level folder.

A maven pom.xml that will create this structure is:

<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.active-queries</groupId>
			<artifactId>active-collection</artifactId>
			<version>${rtgov.version}</version>
			<scope>provided</scope>
		</dependency>
		<dependency>
			<groupId>org.overlord.rtgov.active-queries</groupId>
			<artifactId>acs-loader-osgi</artifactId>
			<version>${rtgov.version}</version>
		</dependency>
		....
	</dependencies>

	<build>
		<finalName>....</finalName>
		<resources>
			<resource>
				<directory>src/main/resources</directory>
				<filtering>true</filtering>
			</resource>
		</resources>
		<plugins>
			<plugin>
				<groupId>org.apache.felix</groupId>
				<artifactId>maven-bundle-plugin</artifactId>
 				<extensions>true</extensions>
				<configuration>
					<instructions>
						<Bundle-SymbolicName>${project.artifactId}</Bundle-SymbolicName>
						<Bundle-Version>${project.version}</Bundle-Version>
						<Bundle-Activator>org.overlord.rtgov.acs.loader.osgi.ACSActivator</Bundle-Activator>
						<Import-Package>
							!javax.inject.*,!javax.enterprise.*,!javax.persistence.*,
                            ....,
                            *
						</Import-Package>
						<Embed-Dependency>*;scope=compile|runtime</Embed-Dependency>
					</instructions>
				</configuration>
			</plugin>
		</plugins>
	</build>

</project>

JEE Container

The Report Definition is deployed within the JEE container as a WAR file with the following structure:

warfile
|
|-META-INF
|    |- beans.xml
|
|-WEB-INF
|    |-classes
|    |    |-reports.json
|    |    |-<custom classes/resources>
|    |
|    |-lib
|       |-reports-loader-jee.jar
|       |-<additional libraries>

As described above, the reports.json file contains the JSON representation of the report definition configuration.

The reports-loader-jee.jar acts as a bootstrapper to load and register the Report Definition.

If custom report generators or scripts 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 will create this structure is:

<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.activity-analysis</groupId>
			<artifactId>reports-loader-jee</artifactId>
			<version>${project.version}</version>
		</dependency>
		<dependency>
			<groupId>org.overlord.rtgov.activity-analysis</groupId>
			<artifactId>reports</artifactId>
			<version>${project.version}</version>
			<scope>test</scope>
		</dependency>
		....
	</dependencies>

</project>

If deploying in JBoss Application Server, then the following fragment also needs to be included, to define the dependency on the core Overlord 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>
	.....