JBoss.orgCommunity Documentation

Runtime Governance: Developer Guide


1. Architecture Overview
1.1. Introduction
1.2. Collection and Reporting
1.2.1. Collection
1.2.2. Reporting
1.2.3. Storage
1.2.4. Notification
1.3. Event Processing/Analysis
1.4. Active Collections
2. Reporting Activity
2.1. Activity Model
2.1.1. Activity Unit
2.1.2. Origin
2.1.3. Context
2.1.4. Activity Type
2.2. Activity Collector
2.2.1. Finding the Activity Collector
2.2.2. Pre-Processing Activity Information
2.2.3. Validating the Activity Event
2.2.4. Managing the Activity Scope
2.2.5. Reporting an Activity Type
2.2.6. Configuring an Activity Unit Logger
2.2.7. Configuring a Collector Context
2.2.8. Simplified Activity Reporter for use by application components
2.3. Activity Server
2.3.1. Recording Activity Units
2.3.2. Querying Activity Units
3. Event Processing
3.1. Custom Predicate
3.2. Custom Event Processor
3.3. Custom Services
3.4. Packaging
4. Active Collections
4.1. Active Collection Source
4.2. Active Change Listeners
4.2.1. Active Change Listener
4.2.2. Abstract Implementation
4.3. Accessing Active Collections
4.3.1. Retrieve an Active Collection
4.3.2. Create a Derived Active Collection
4.3.3. Register for Active Change Notifications

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:

images/SAM1ActivityReporting.png

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

images/SAM2EventProcessorNetwork.png

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.

images/SAM3ServiceActivityPresentation.png

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.

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

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

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

ProcessStarted

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

Attributes include: process type, instance id and version

ProcessCompleted

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

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

ProcessVariableSet

This activity type will be recorded when a process variable’s value is set or modified.

Attributes include: process type, instance id and variable name/type/value

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, that will be reported to the activity server, 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();

sentreq.setServiceType(serviceType);
sentreq.setOperation(opName);
sentreq.setContent(content);
sentreq.setMessageType(mesgType);
sentreq.setMessageId(messageId);

activityCollector.record(sentreq);

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);

sentreq.setContent(modifiedContent);

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. Where injection is not possible, then a default implementation of the interface can be instantiated.

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

@Service(InventoryService.class)
public class InventoryServiceBean implements InventoryService {

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

    private org.overlord.rtgov.client.ActivityReporter _reporter=
                new org.overlord.rtgov.client.DefaultActivityReporter();

    public InventoryServiceBean() {
        ....
    }

    @Override
    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:

                <dependency>
                        <groupId>org.overlord.rtgov.integration</groupId>
                        <artifactId>rtgov-client</artifactId>
                        <version>${rtgov.version}</version>
                </dependency>

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.

Tip

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.

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.
  • properties - used to initialize the derived collection.

Currently the only property that can be set is a boolean named active, which defaults to true.

If the active property is true, then 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.

If the active property is false, then whenever the derived collection is queried, the predicate will be applied to the parent collection to obtain the current set of results. This configuration should only be used where the predicate is based on volatile information, and therefore the results in the derived collection would be changing independently of changes applied to the parent 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) {
        java.util.Map<String,Object> properties=.....;

        alist = (ActiveList)acmManager.create(childName,
                    parent, predicate, properties);
}