Scribble is a text based language for describing protocols, or multi-party session types, that illustrate the interactions that can occur between two or more participants.

This article will explain how a protocol speciication can be used to monitor a stream of events, to determine whether they are valid in respect of the protocol. Firstly we will provide a demonstration of the current monitoring capability, used to simulate a protocol against a series of events, and then describe the various steps required to create, initialize and use the monitor. Finally we will provide the details for downloading and running a simple standalone monitoring demo.

Monitor in action

Download the Scribble binary distribution from http://www.jboss.org/scribble/downloads (current version is 2.0.0.M6). Once downloaded, unpack in a suitable location and go to the 'bin' folder and perform the following command:

./simulate.sh ../samples/models/monitor/Purchasing@Buyer.spr ../samples/models/monitor/Purchasing@Buyer.events

This will simulate the events defined in the Purchasing@Buyer.events file,

send,Order,Broker
receive,Confirmation,Broker

against the protocol defined in the Purchasing@Buyer.spr file.

import Order;
import CreditCheck;
import CreditOk;
import InsufficientCredit;
import Confirmation;
import OutOfStock;

protocol Purchasing@Buyer (role Broker) {

    Order to Broker;

    choice {
        Confirmation from Broker;
    } or {
        OutOfStock from Broker;
    } or {
        InsufficientCredit from Broker;
    }
}

The output from performing this command should be:

INFO: SIMULATE ../samples/models/monitor/Purchasing@Buyer.spr ../samples/models/monitor/Purchasing@Buyer.events
INFO: Validated SendMessage Order to Broker
INFO: Validated ReceiveMessage Confirmation from Broker

To demonstrate that the monitor will detect invalid events, simply edit the events file and (for example) change the message type. For example, if we add an 'X' to the end of the Confirmation message type, and then re-run the command, this would result in the following output:

INFO: SIMULATE ../samples/models/monitor/Purchasing@Buyer.spr ../samples/models/monitor/Purchasing@Buyer.events
INFO: Validated SendMessage Order to Broker
ERROR: ReceiveMessage ConfirmationX from Broker

How to Monitor a Protocol

This section describes the various steps required to monitor a protocol. In the simulation example above, all of these steps are performed within a single application, however in a realworld scenario this does not necessarily need to be the case - e.g. the monitorable representation could be derived from the protocol and stored in a repository, ready to be loaded into the monitors when appropriate.

The code for the 'simulate' command can be found here, and may be useful when reading the following sections. Alternatively the simple monitoring demo, described at the end of the article, can be reviewed against the following information.

Parse the Protocol

Parsing the protocol specification simply (a) validates that it is a valid protocol syntax, and (b) converts it into an object model representation. It is also possible to submit the protocol model to additional validation modules, which will ensure it is valid according to other properties of interest, but for this article this step will be skipped.

java.io.File file=...... ;    // File containing protocol specification
org.scribble.common.resource.Content content=new org.scribble.common.resource.FileContent(file);
org.scribble.common.logging.Journal journal=......;
org.scribble.protocol.parser.ProtocolParserManager protocolParserManager=......;

org.scribble.protocol.model.ProtocolModel model=
                            protocolParserManager.parse(content, journal,
                                    new org.scribble.protocol.DefaultProtocolContext(protocolParserManager,
                                    new org.scribble.common.resource.DefaultResourceLocator(file.getParentFile())));

The ProtocolParserManager may be initialized (through OSGi or explicitly) with multiple scribble protocol parsers, selected based on the input representation. This enables a scribble protocol model to be derived from other notations, such as BPMN2, WS-CDL, etc, as well as the standard text based notation.

The parse operation is performed on the protocol parser manager, supplying:

• the content, which in this case wraps the file containing the scribble protocol
• the journal, which is used to log errors, warnings and other information
• the protocol context, which provides the parser with additional services it may require, including a reference to the protocol parser manager (so that as part of parsing the protocol, it can parse other external protocols), and the resource locator, used to locate other externally referenced (e.g. protocol) resources

If the protocol is valid, then a model will be returned that can be passed to other scribble modules for further processing.

Derive the Monitoring Representation

The first step is to obtain a reference to the monitor exporter. As with the parser above, there is a ProtocolExportManager component that is responsible for managing all of the available protocol exporters - each exporter dealing with exporting the protocol to a different format (e.g. text, or in this case a monitorable representation). In an OSGi container, the set of protocol exporters within the manager would be initialized by the OSGi container. In non-OSGi container environments, this initialization would need to be achieved explicitly - or the monitor based protocol exporter obtained through other means.

org.scribble.protocol.export.ProtocolExporter exporter=
                        protocolExportManager.getExporter("monitor");

if (exporter != null) {
            ByteArrayOutputStream os=new ByteArrayOutputStream();

            try {
                exporter.export(model, m_journal, os);

                java.io.InputStream prtis=new java.io.ByteArrayInputStream(os.toByteArray());

                org.scribble.protocol.monitor.model.Description protocol=
                        org.scribble.protocol.monitor.util.MonitorModelUtil.deserialize(prtis);

                prtis.close();

                // Use the protocol monitor description
                .......

            } catch(Exception e) {
                     .......
            }
}

The exporter places the exported representation on the supplied output stream, which then needs to be converted into an object model representation (org.scribble.protocol.monitor.model.Description) for subsequent use in the application.

Defining a Monitoring Context

The MonitorContext interface provides services to the monitor. Currently this interface only consists of the following:

public interface MonitorContext {
            public Result validate(MessageNode mesgNode, Message mesg);
}

The validate method simply takes the monitoring node (from the monitorable representation), and the message to be validated, and determine whether it is valid or not. The message node currently has a list of annotations associated with it, which can be used to carry additional information that can be used to validate this message in the context of the session.

NOTE: Need to update this API to pass the session, as currently it is only validating the message against the node, and therefore does not need access to any additional session information.

There is a default implementation of the monitor context,

org.scribble.protocol.monitor.MonitorContext context=new org.scribble.protocol.monitor.DefaultMonitorContext();

Using this approach means that the monitoring engine does not need to be concerned with how the validation is performed, it simply moves the session through the state machine defined by the protocol, according to the series of message events presented to it. Custom monitoring context implementations can be used to validate the message against the session context, taking into account any available annotations.

Initializing a Session

The Session component represents the information concerning the current status of a conversation instance being monitored against a protocol. The responsibility for the management and persistence of sessions is with the application that embeds the monitor. The monitor itself simply updates the session according to the protocol and series of events that are processed.

It is the responsibility of the containing environment to determine if a new session needs to be initialized, or whether an existing session should be retrieved from a persistent store. If a new session is required, the following code shows how this can be done:

org.scribble.protocol.monitor.ProtocolMonitor protocolMonitor=.....;
org.scribble.protocol.monitor.MonitorContext context=......;
org.scribble.protocol.monitor.model.Description protocol=......;

// Create a new session
Session conv=new DefaultSession();

// Initialize the session against the protocol
protocolMonitor.initialize(context, protocol, conv);

This will cause the session to be initialized and be ready to process the first event.

Monitoring Events

The final step is to actually monitor the events. The interface for the monitor is:

public interface ProtocolMonitor {
          public void initialize(MonitorContext context, Description protocol, Session conv);

          public Result messageSent(MonitorContext context, Description protocol,
                             Session conv, String role, Message mesg);

          public Result messageReceived(MonitorContext context, Description protocol,
                    Session conv, String role, Message mesg);
}

The initialize method was explained in the previous section.

The messageSent and messageReceived methods are very similar, they just reflect the direction of the message from the perspective of the role being monitored. The context parameter represents the MonitorContext, as explained above, which provides validation services to the monitor. The Description represents the monitorable representation of the Scribble protocol. The Session represents the information regarding the current status of the conversation instance. The mesg parameter represents the message being sent or received.

NOTE: The role parameter is intended to be the destination role of the message - however this may not be known by the monitor container, and is therefore currently optional. Not sure how relevant this is???

Simple Monitor Demo

A simple monitor demo can be downloaded from here. The zip should be downloaded and unpacked in a suitable location.

This project uses maven to build and run the example as a JUnit testcase, and therefore you will need to install maven if not already available on your system.

When the zip has been unpacked, go to the top level folder and type:

mvn clean test

This will build the demo and run two testcases, one with valid events being monitored, and another with an invalid event.