JBoss.orgCommunity Documentation
There are two ways in which activity information can be collected for further processing by the Runtime Governance server.
This section will explain how to use both approaches.
This section describes how activities can be collected from different execution environments.
To instrument a switchyard application, that is deployed as a war, is simply a case of including a maven dependency and configuring a manifest property within the built war file.
The maven dependency added to the pom.xml for the SwitchYard project is:
<dependency>
<groupId>org.overlord.rtgov.integration</groupId>
<artifactId>rtgov-switchyard</artifactId>
<version>${rtgov.version}</version>
</dependency>
and the following build plugin, to include the dependency between the SwitchYard application and the Overlord Runtime Governance infrastructure:
<build>
<plugins>
...
<plugin>
<artifactId>maven-war-plugin</artifactId>
<configuration>
<!-- Java EE 6 doesn't require web.xml, Maven needs to catch up! -->
<failOnMissingWebXml>false</failOnMissingWebXml>
<webResources>
<resource>
<directory>target/switchyard_xml</directory>
</resource>
</webResources>
<archive>
<manifestEntries>
<Dependencies>deployment.overlord-rtgov.war</Dependencies>
</manifestEntries>
</archive>
</configuration>
</plugin>
</plugins>
</build>
The Activity Interceptor mechanism provides the means to install event processing capabilities within the activity collection environment (i.e. co-located with the execution of the business transaction).
The main reason for performing analysis of the activity events at this stage in the runtime governance lifecycle is to enable the analysis to potential block the business transaction. For an example of such a case, please see the synchronous policy sample.
The Activity Interceptor 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 Interceptors. 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.ep.service.infinispan.InfinispanCacheManager"
}
}
}
}]
This example illustrates the configuration of a single Activity Interceptor with the top level elements:
| Field | Description |
|---|---|
name | The name of the Activity Interceptor. |
version | The version of the Activity Interceptor. If multiple versions of the same named Activity Interceptor are installed, only the newest version will be used. Versions can be expressed using three schemes: Numeric - i.e. simply define the version as a number Dot Format - i.e. 1.5.1.Final Any alpha, numeric and symbols. |
predicate | The optional implementation of the |
eventProcessor | The implementation of the |
When comparing versions, for example when determining whether a newly deployed Activity Interceptor 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 Interceptors are deployed within the JEE container as a WAR file with the following structure:
warfile | |-META-INF | |- beans.xml | |-WEB-INF | |-classes | | |-ai.json | | |-<custom classes/resources> | | | |-lib | |-ai-loader-jee.jar | |-<additional libraries>
The ai.json file contains the JSON representation of the Activity Interceptor configuration.
The ai-loader-jee.jar acts as a bootstrapper to load and register the Activity Interceptors.
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>ai-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>
.....
To enable the Runtime Governance infrastructure, and the user policies/rules that are defined within it, to make the most effective use of the activities that are reported, it is necessary to process certain events to extract relevant information for use in:
It is also important to control what information is distributed with the actvity events, for both size (i.e. performance) and security reasons. By default information content should not be distributed, unless an information processor has been defined to explicitly indicate how that information should be represented (if at all) within the activity event.
This section explains how information processors can be configured and deployed along side the business applications they are monitoring.
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",
"namespaces":{
"orders":"urn:switchyard-quickstart-demo:orders:1.0"
},
"expression":"/orders:submitOrder/order/orderId"
}
}],
"properties":[{
"name":"customer",
"evaluator":{
"type":"xpath",
"namespaces":{
"orders":"urn:switchyard-quickstart-demo:orders:1.0"
},
"expression":"/orders:submitOrder/order/customer"
}
}]
},
"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",
"namespaces":{
"orders":"urn:switchyard-quickstart-demo:orders:1.0"
},
"expression":"/orders:makePayment/payment/customer"
}
},{
"name":"amount",
"evaluator":{
"type":"xpath",
"namespaces":{
"orders":"urn:switchyard-quickstart-demo:orders:1.0"
},
"expression":"/orders:makePayment/payment/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:
| Field | Description |
|---|---|
name | The name of the Information Processor. |
version | The version of the Information Processor. If multiple versions of the same named Information Processor are installed, only the newest version will be used. Versions can be expressed using three schemes: Numeric - i.e. simply define the version as a number Dot Format - i.e. 1.5.1.Final Any alpha, numeric and symbols. |
typeProcesors | The map of type processors - one per type, with the type name being the map key. |
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:
| Field | Description |
|---|---|
contexts | The list of context evaluators. |
properties | The list of property evaluators. |
script | An optional script that is used to do any other processing that may be required. |
transformer | An optional transformer that determines how this information type will be represented within an activity event. |
Context Evaluator
The fields associated with the Context Evaluator component are:
| Field | Description |
|---|---|
type | The context type, e.g. Conversation, Endpoint or Message. |
expression | The expression evaluator used to derived the context value. See further down for details. |
optional | Optional field that indicates whether the value being extracted by the expression is optional. The default is false. If a value is not optional, but the expression fails to locate a value, then an error will be reported |
Property Evaluator
The fields associated with the Property Evaluator component are:
| Field | Description |
|---|---|
name | The property name being initialized. |
expression | The expression evaluator used to derive the property value. See further down for details. |
optional | Optional field that indicates whether the value being extracted by the expression is optional. The default is false. If a value is not optional, but the expression fails to locate a value, then an error will be reported |
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:
| Field | Description |
|---|---|
type | The type of expression evaluator to use. Currently only support mvel or xpath. |
expression | The expression to evaluate. |
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:
| Field | Description |
|---|---|
type | The type of script evaluator to use. Currently only support mvel. |
expression | The expression to evaluate. |
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:
| Field | Description |
|---|---|
type | The type of transformer to use. Currently support serialize and mvel. |
The serialize transformer does not take any other properties. It 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.
The mvel transformer takes the following additional fields:
The MVEL transformer script is supplied the following variable for its use:
| Field | Description |
|---|---|
expression | The mvel expression to transform the supplied information. |
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":{
"contexts":[{
"type":"Conversation",
"evaluator":{
"type":"xpath",
"namespaces":{
"orders":"urn:switchyard-quickstart-demo:orders:1.0"
},
"expression":"/orders:submitOrder/order/orderId"
}
}],
"properties":[{
"name":"customer",
"evaluator":{
"type":"xpath",
"namespaces":{
"orders":"urn:switchyard-quickstart-demo:orders:1.0"
},
"expression":"/orders:submitOrder/order/customer"
}
}],
"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>
.....
This section explains how activity information can be reported to, and queried from, the Activity Server via a RESTful service.
POST request to URL: <host>/overlord-rtgov/activity/store
The request contains the list of ActivityUnit objects encoded in JSON. For example,
[{
"id":"TestId1",
"activityTypes":[{
"type":"RequestSent",
"context":[{
"value":"12345"
},{
"value":"abc123",
"type":"Endpoint"
},{
"value":"ABC123",
"type":"Message"
}],
"content":"....",
"serviceType":"{http://service}OrderService",
"operation":"buy",
"fault":"MyFault",
"messageType":"{http://message}OrderRequest",
"timestamp":1347028592880
},{
"type":"ResponseReceived",
"context":[{
"value":"12345"
},{
"value":"ABC124",
"type":"Message"
}],
"content":"....",
"serviceType":"{http://service}OrderService",
"operation":"buy",
"fault":"OutOfStock",
"messageType":"{http://message}OutOfStock",
"replyToId":"ABC123",
"timestamp":1347028593010
}],
"origin":{
"host":"Saturn",
"port":"8010",
"principal":"Fred",
"node":"Saturn1",
"thread":"Thread-1"
}
},{
.....
}]
POST request to URL: <host>/overlord-rtgov/activity/query
The request contains the JSON encoding of the Query Specification, which has the following properties:
| Property | Description |
|---|---|
id | Optionally specifies the activity unit id that is required. |
fromTimestamp | Optionally specifies the start date/time for the activity units required. If not specified, then the query will apply to activity units from the first one recorded. |
toTimestamp | Optionally specifies the end date/time for the activity units required. If not specified, then the query will relate up to the most recently recorded activity units. |
expression | An optional expression that can be used to specify the activity events of interest. |
format | Optionally specifies the format of the expression. The value must be supported by the configured activity store. |
The response contains a list of ActivityType objects encoded in JSON, which would be similar in form to the example shown above when recording a list of activity units.
GET request to URL: <host>/overlord-rtgov/activity/unit?id=<unitId>
The <unitId> represents the identifier associated with the ActivityUnit that is being retrieved.