JBoss.orgCommunity Documentation

Runtime Governance: Developer Guide

This section will outline the architecture of the Runtime Governance architecture, prior to going into further details in the following sections.

The first stage of the architecture performs the functions illustrated in this diagram:


The following diagram illustrates how a node within an Event Processor Network functions to process the inbound event information.


The Event Processor Network (EPN) is a graph based mechanism for processing a series of events. In the context of the infrastructure, one or more networks can be registered to receive the activity information (as notifications) from the Activity Server and process it (filter, transform, analyse, etc) using whatever means is appropriate.

Each network defines a graph of nodes connected by links that transfer the results from the source node to the target node. The graphs can subscribe to event subjects, to identify the information they are interested in, and nominate the node(s) within the network that will process the information received on that subject. The nodes can also publish their results to event subjects, for other networks to further process - so this provides a decoupled way for networks to exchange information.

Each node defines an optional predicate, that can be used to determine whether the event is of interest, and an event processor to perform the actual task. An example of an "out of the box" event processor is one used to trigger rules (using Drools) to process the events.

The Event Processor Network (EPN) can be versioned, so that when a new version of a network is deployed, any events that are being processed by the old version will continue to be processed using that network, while new events being dispatched to the network will be handled by the newer version. This overcomes any potential issues where the structure of the network changes between versions.

The nodes can also be configured to generate different levels of notification, which can be used by other applications/components to observe the information being processed through the network (e.g. events that passed the predicate evaluation, results from the event processor, etc.). These notifications are distributed to named "notification subjects", enabling observing components to remain decoupled from the details of which (or how many) networks/nodes are producing results for that subject.

The Active Collection mechanism provides a capability for storing processed events (and derived analysis information) in a manner that can be accessed by end users, as well as enable those end users/applications to be actively notified when any changes occur.


The Active Collection mechanism is a variation on the standard collection concept, where interested parties can register interest in changes that occur to the contents of a collection (e.g. list, map, etc). This is one of the mechanisms that will be used to maintain information that is to be presented to users (e.g. via the Gadget Server).

The information within a particular Active Collection is managed by an Active Collection Source, which effectively acts as an adapter between the actual source of the information and the Active Collection. For example, an "out of the box" implementation of an Active Collection Source is provided to observe different types of information produced by an Event Processor Network.

The generic Active Collection Source implementation includes the ability to aggregate information which is then stored as a summary within the Active Collection, perform routine maintenance tasks and tidy up collection entries based on configured criteria (e.g. max size of the collection, max duration an item should exist in the collection, etc).

As well as creating these top level active collections, associated with configured Active Collection Sources, it is also possible to create derived (child) collections from these top level collections. These derived collections have a predicate that determines whether an entry in the parent collection is relevant to the child collection. This can be used to manage specific sub-sets, and essentially provides an active query mechanism, enabling interested clients to observe changes to that child collection.

The section provides an overview of the Activity Model. This model defines the set of events (or situations) that can be reported to identify what is happening during the execution of a business transaction.

The context items represent information that can be used to correlate the activities within the unit against other Activity Units, as well as identify information information that may be useful when attempting to retrieve the unit.

The context has the following three pieces of information:

  • type - the context type, explained below
  • name - the name associated with the context information
  • value - the value of the context information

The different context types that can be defined are:

Type Constant Description


The conversation id, which can be used to correlate activities across service boundaries and is unique to a particular business transaction instance.


The endpoint id, which can be used to correlate activities within a service boundary (e.g. BPM process instance id), and which is also unique to a particular business transaction instance.


The unique id for a message being sent and/or received. The message id may only be valid within the scope of an endpoint, as its value may not be carried with the message contents to the recipient. A common usage will be to correlate a response against the originating request within the same endpoint.


The context represents a property value extracted from business information associated with the activities. The property values will not be unique to a particular business transaction instance, but are used to identify a relationship between activity units across business transactions. These fields can also be used to carry excerpts from messages, rather than recording the full message contents in the activity events.

All activity events are derived from an Activity Type superclass. This class has the following information:

  • activity unit id
  • activity unit index
  • timestamp
  • a set of contexts

The only piece of information that needs to be provided by the reporting component is the timestamp, and optionally some activity type specific contexts. The other information will be initialized by the infrastructure prior to persisting the Activity Unit, as a way to enable the specific Activity Type instance to be located. This may be required during the analysis of Activity Units.

The BPM (Business Process Management) specific activity events are used to record the lifecycle and state transitions that occur when a business process (associated with a description language such as BPMN2 or WS-BPEL) is executed within a runtime engine, in support of a business transaction.

These business processes tend to be "long running", in that they handle multiple requests and responses over a period of time, all being correlated to the same process instance. This means that activities generated as a result of this execution must also be correlated to \(i) the specific XA transaction in which they are performed, (ii) the process instance that holds their state information in the BPM engine, and (iii) the conversation associated with the particular business transaction.

This does not mean that all Activity Units the contain activity information from the BPM engine need to have all three types of correlation information. For example, the initial Activity Unit for a business process instance may identify (i) and (ii), which will establish a unique process instance id. A subsequent Activity Unit may then define the same process id for (ii), as well as a conversation id (iii) that can then be used to tie any Activity Unit relates with the process instance id to that conversation - i.e. all Activity Units with the same process instance id become directly or indirectly correlated to the conversation id that may only be declared in some of the Activity Units.

Activity Type Description


This activity type will be recorded when a process instance is initially started.

Attributes include: process type, instance id and version


This activity type will be recorded when a process instance completes.

Attributes include: instance id and status (either success or fail)


Work is still required to specify the different BPM related activity types that may be required.

The Activity Collector is an embedded component that can be used to accumulate activity information from the infrastructure used in the execution of a business transaction. The activity information is then reported to the Activity Server (described in the following section) implicitly, using an appropriate Activity Logger implementation. The default Activity Logger implementation operates efficiently by providing a batching capability to send activity information to the server based either on a regular time interval, or a maximum number of activity units, whichever occurs first.

An Activity Scope is a way of grouping a range of different activity types into a single logical unit. It should generally represent the same scope as a XA transaction, to emcompass all of the work that was achieved within that transaction - and equally be discarded if the transaction is rolled back.

When the first activity is reported within the scope of a XA transaction, then the scope will automatically be started. When that transaction subsequently commits, the Activity Unit (i.e. the collection of activities accumulated during that scope) will be reported to the Activity Server.

However if activities are performed outside the scope of a XA transaction, then the component reporting the activity information can either explicitly start a scope, or just report the activity information.

If no scope exists, and an activity type is reported, then it will simply be reported to the activity server as a single event. The disadvantage of this approach is that it is less efficient, both in terms of reporting due to the duplication of certain header information, and for subsequent analysis. Having multiple activity events defined in a single unit, related to the transaction, provides added value to inter-relating the different events - providing some implied correlation that would not exist if the events were independently reported to the Activity Server.

As described above, activity information is reported to the server as an Activity Unit, containing one or more actual activity events. The activity event is generically known as an Activity Type.

The Activity Collector mechanism removes the need for each component to report general information associated with the Activity Unit, and instead is only responsible for reporting the specific details associated with the situation that has occurred.

The set of different Activity Types that may be reported is outside the scope of this section of the documentation, and so for the purpose of illustration we will only be using a subset of the SOA related activity events. For more informaton on the available event types, please refer to the javadocs.

To report an event, simply create the specific Activity Type and invoke the record method:

org.overlord.rtgov.activity.model.RequestSent sentreq=new org.overlord.rtgov.activity.model.soa.RequestSent();



For certain types of event, it may also be appropriate to invoke an information processor(s) to extract relevant context and property information, that can then be associated with the activity event. This is achieved using the following:

Object modifiedContent=_activityCollector.processInformation(null,
          mesgType, content, sentreq);


The activity collector can be used to process relevant information, supplying the activity type to enable context and property information to be defined. The result of processing the information may be a modified version of the content, suitably obsfucated to hide any potentially sensitive information from being distributed by the governance infrastructure.

The first parameter to the processInformation() method is an optional information processor name - which can be used to more efficiently locate the relevant processor if the name is known.

The Activity Unit Logger is the component responsible for logging the activity unit that is generated when the endScope method is invoked on the collector (either explicitly or implicitly by the XA resource manager).

This interface has three methods:

  • init - this method initializes the activity unit logger implementation
  • log - supplied the Activity Unit to be logged
  • close - this method closes the activity unit logger implementation

Although the general Activity Collector mechanism can be used, as described in the previous sections, an injectable ActivityRecorder component is provided to enable applications to perform simple activity reporting tasks.

For example, the sample SwitchYard order management application uses this approach:

public class InventoryServiceBean implements InventoryService {

    private final Map<String, Item> _inventory = new HashMap<String, Item>();

    private org.overlord.rtgov.jee.ActivityReporter _reporter=null;

    public InventoryServiceBean() {

    public Item lookupItem(String itemId) throws ItemNotFoundException {
        Item item = _inventory.get(itemId);

        if (item == null) {

            if (_reporter != null) {
                _reporter.logError("No item found for id '"+itemId+"'");

            throw new ItemNotFoundException("We don't got any " + itemId);


        return item;

The ActivityReporter enables the application to perform the following tasks:

Method Description

logInfo(String mesg)

Log some information

logWarning(String meg)

Log a warning

logError(String mesg)

Log an error

report(String type, Map<String,String> props)

Record a custom activity with a particular type and associated properties

report(ActivityType activity)

Record an activity

However this API cannot be used to control the scope of an ActivityUnit. It is expected that this would be handled by other parts of the infrastructure, so this API is purely intended to simplify the approach used for reporting additional incidental activities from within an application.

The maven dependency required to access the ActivityReporter is:


The Activity Server is responsible for:

  • Recording Activity Units describing the activities that occur during the execution of business transactions in a distributed environment.
  • Query suport to retrieve previously recorded Activity Units

The Activity Server can be used to record a list of Activity Units generated from activity that occurs durig the execution of a business transaction. The Activity Units represent the logical grouping of individual situations that occur within a transaction (e.g. XA) boundary.

This section will show the different ways this information can be recorded, using a variety of bindings.


Where possible, the Activity Collector mechanism described in the previous section should be used to aggregate and record the activity information, as this is more efficient that each system individually reporting events to the server.

The Activity Server can be used to query a list of Activity Units that meet a supplied query specification. This section will show the different ways this information can be queried, using a variety of bindings.

The EventProcessor, and supporting components, can be used either directly within the Activity Collection mechanism or from nodes within an Event Processor Network. This section of the Developer Guide will discuss how custom Predicates and Event Processors are defined.

The Active Collection mechanism provides a means of actively managing a collection of information. For a more details explanation of the mechanism, see the User Guide.

This section explains how to:

  • implement an Active Collection Source, which can be used to subscribe to a source of information which can result in data being inserted, updated and removed from an associated active collection.
  • implement an Active Change Listener that can associated with an Active Collection Source, and automatically notified of changes to an associated Active Collection
  • write a custom application for accessing Active Collections

The Active Collection Source can be considered the adapter between the actual source of events/information and the Active Collection. The Active Collection Source is responsible for managing the insertion, update and deletion of the objects within the associated Active Collection, based on situations that occur in the source.

An example of a derived Active Collection Source implementation, that is packaged with the infrastructure, can be used to listen for events produced by nodes in an Event Processor Network and insert these events in the Active Collection.

To create a new type of Active Collection Source, simply derive a class from the org.overlord.rtgov.active.collection.ActiveCollectionSource class and implement the following methods:

Method Description

void init()

This method is invoked when the Active Collection Source is registered, and should be used to create the subscription to the relevant source of information. The implementation of this method MUST call the init() method on the super class first.

void close()

This method is invoked when the Active Collection Source is unregistered, and should be used to unsubscribe from the source of information. The implementation of this method MUST call the close() method on the super class first.

When a situation occurs on the source, that requires a change in the associated Active Collection, then the derived implementation can call one of the follow methods on the Active Collection Source:

Method Description

public void insert(Object key, Object value)

This method is called to insert a new element into the collection. The value is the information to be inserted. The key is potentially optional, depending on the nature of the active collection:

List - the key is optional. If specified, then it MUST be an integer representing the index where the value should be inserted.

Map - the key represents the map key to be associated with the value, and is therefore not optional.

public void update(Object key, Object value)

This method is called to update an existing element within the collection. The value is the information to be updated. The key is potentially optional, depending on the nature of the active collection:

List - the key is optional. If specified, then it MUST be an integer representing the index of the value to be updated. If not specified, then the value will be used to locate the index within the list.

Map - the key represents the map key associated with the value, and is therefore not optional.

public void remove(Object key, Object value)

This method is called to remove an element from the collection. The value is the information to be updated. The key is potentially optional, depending on the nature of the active collection:

List - the key is optional. If specified, then it MUST be an integer representing the index of the value to be removed. If not specified, then the value will be used to locate the index within the list.

Map - the key represents the map key associated with the value, and is therefore not optional. However in this situation the value is optional.

This section explains how to implement a listener to deal with changes that occur within an Active Collection.

The first sub-section details with general implementations of this interface, that may be used within custom applications. The second sub-section will deal with a specific type of listener that can be configured with an Active Change Source (discussed in the previous section), and automatically initialized when the Active Change Source is registered.

This section explains how to:

  • retrieve an existing active collection
  • create a derived active collection
  • register for active change notifications

There are two ways to retrieve an active collection.

As discussed in a previous section, Active Collections are created as a bi-product of registering an Active Collection Source. The Active Collection Source is registered with an Active Collection Manager, which creates the collection to be updated from the source. This Active Collection then becomes available for applications to retrieve from the manager, for example:

import org.overlord.rtgov.active.collection.ActiveCollectionManager;
import org.overlord.rtgov.active.collection.ActiveList;


private static final String ACM_MANAGER = "java:global/overlord-rtgov/ActiveCollectionManager";


InitialContext ctx=new InitialContext();

ActiveCollectionManager acmManager =

ActiveList list = (ActiveList)

This is the approach used to retrieve what can be considered "top level" active collections. These are the collections directly maintained by the Active Collection Manager, each with an associated Active Collection Source defining the origin of the collection changes. The following section shows how further active collections can be derived from these "top level" collections, to refine the information.

The maven dependency required to access the ActiveCollectionManager and active collections is:


The "top level" active collections defined in the previous section reflect the information changes as identified by their associated Active Collection Source. However in some situations, only a subset of the information is of interest to an application. For these situations, it is possible to derive a child active collection by specifying:

  • parent - the parent collection from which the child may be derived. Although this will generally be the name of a "top level" collection, it is possible to derive a collection from another child collection, enabling a tree to be formed.
  • predicate - a predicate is specified to determine whether information in a parent collection (and subsequently its changes), are relevant to the child collection.

When a child collection is initially created, the predicate will be used to filter the contents of the parent collection to identify the initial subset of values that are relevant for the child collection. Once initialized, the child collection effectively subscribes to the change notifications of the parent collection, and uses the predicate to determine whether the change is applicable, and if so, applies the change to the child collection.

import org.overlord.rtgov.active.collection.predicate.Predicate;
import org.overlord.rtgov.active.collection.ActiveCollectionManager;
import org.overlord.rtgov.active.collection.ActiveList;


Predicate predicate=.....;

ActiveList parent = (ActiveList)acmManager.getActiveCollection(parentName);

if (parent != null) {
        alist = (ActiveList)acmManager.create(childName,
                    parent, predicate);