Scribble Java Developer Guide

This artifact contains general interfaces/classes for issue logging, context, resources and the protocol model (local and global variants).

The parser is the component responsible for taking a text based description of a Scribble protocol and transforming it into an object model. As part of this process, it will verify that the syntax of the protocol description is valid, and report any errors using the supplied org.scribble.logging.IssueLogger.

String path=....;		// Colon separate directory paths where scribble modules are located
java.io.InputStream is=....;	// Input stream containing text description of scribble protocol

org.scribble.parser.ProtocolParser pp=new org.scribble.parser.ProtocolParser();
org.scribble.logging.IssueLogger logger=new org.scribble.logging.ConsoleIssueLogger();
org.scribble.resources.DirectoryResourceLocator locator=new org.scribble.resources.DirectoryResourceLocator(path);

org.scribble.context.ModuleLoader loader=new org.scribble.parser.ProtocolModuleLoader(pp, locator, logger);

org.scribble.resources.Resource res=new org.scribble.resources.InputStreamResource(path, is);

org.scribble.model.Module module=pp.parse(res, loader, logger);

The last line of this example shows the parser being involved. It takes three parameters:

If the parser returns a module, then it means that it was successfully parsed. Otherwise the syntax errors will be reported to the issue logger and no module will be returned.

The validator is the component responsible for evaluating a protocol module (org.scribble.model.Module) to determine if it conforms to a set of predefined rules (e.g. wellformedness conditions). As with the parser, any issues will be reported to the supplied org.scribble.logging.IssueLogger.

org.scribble.logging.IssueLogger logger=...;
org.scribble.resources.Resource res=...;
org.scribble.context.ModuleLoader loader=...;
org.scribble.model.Module module=...;

org.scribble.context.ModuleContext context=new org.scribble.context.DefaultModuleContext(res, module, loader);

org.scribble.validation.ProtocolValidator pv=new org.scribble.validation.ProtocolValidator();

pv.validate(context, module, logger);

Most of the components used in this example validation were introduced in the parser section above. The new components in this example are the ProtocolValidator, which will perform the validation, and the ModuleContext. As discussed in a previous section, the module context provides access to members (e.g. type or protocol definitions) in a particular module, or associated module.

In the context of Scribble, projection is the term used to describe extracting the local endpoint behaviour of a role defined within a global protocol. The global protocol describes the interactions between multiple parties, whereas the local protocol described the interactions from a particular role’s perspective.

Being able to filter out just the responsibilies of an individual role, from the potentially complex set of interactions that may be defined in a global protocol between many participants, is important - primarily for being able to determine whether an implementation of that role (endpoint) is statically or dynamically conforming to the expected behaviour.

org.scribble.logging.IssueLogger logger=...;
org.scribble.resources.Resource res=...;
org.scribble.context.ModuleLoader loader=...;
org.scribble.model.Module module=...;

org.scribble.context.ModuleContext context=new org.scribble.context.DefaultModuleContext(res, module, loader);

org.scribble.projection.ProtocolProjector projector=new org.scribble.projection.ProtocolProjector();

java.util.Set<Module> projected=projector.project(context, module, logger);

The code is very similar to the validation example, with the exception that we are creating a ProtocolProjector and the projection results in a set of modules representing the local protocol definitions.

To efficiently monitor a running system, to ensure that it is conformed to one or more roles within a protocol description, it is necessary to transform the text based description (and even the object model representation) into a form that can more effectively be used to drive a runtime monitoring solution.

org.scribble.context.ModuleLoader loader=...;
org.scribble.resources.Resource res=...;

org.scribble.model.local.LProtocolDefinition lp=...;	// Obtain the required local protocol definition

org.scribble.monitor.export.MonitorExporter exporter=new org.scribble.monitor.export.MonitorExporter();

org.scribble.context.ModuleContext context=new org.scribble.context.DefaultModuleContext(res, lp.getModule(), loader);

org.scribble.monitor.model.SessionType type=exporter.export(context, lp);

The first step is to obtain the module that contains the local protocol definition to be monitored. This can ether be achieved by parsing a textual representation of a local protocol definition, or by projecting the local modules from a global module.

Once the module is obtained, then the specific local protocol definition can be retrieved. As a module may contain multiple local protocol definitions, it is important to select the one that represents the initial (or top level) protocol definition from the perspective of what needs to be monitored.

Once the exporter has been instantiated, invoke the export method with the selected local protocol definition. This will export the protocol definition into a state machine representation associated with the returned org.scribble.monitor.model.SessionType object. This object will be used in subsequent runtime monitoring session instances to define the behavioural type being verified.

The trace model can be serialized as a JSON representation, e.g.

{
	"name":"RequestResponse-1",
	"steps":[{
		"type":"MessageTransfer",
		"message":{
			"operator":"buy",
			"types":["{http://scribble.org/example}OrderRequest"],
			"values":[""]
		},
		"fromRole":"Buyer",
		"toRoles":["Seller"]
	},{
		"type":"MessageTransfer",
		"message":{
			"operator":"buy",
			"types":["{http://scribble.org/example}OrderResponse"],
			"values":[""]
		},
		"fromRole":"Seller",
		"toRoles":["Buyer"]
	}],
	"simulations":[{
		"roleSimulators":{
			"Buyer":{
				"type":"MonitorRoleSimulator",
				"module":"scribble.examples.RequestResponse",
				"role":"Buyer",
				"protocol":"First"
			},
			"Seller":{
				"type":"MonitorRoleSimulator",
				"module":"scribble.examples.RequestResponse",
				"role":"Seller",
				"protocol":"First"
			}
		}
	}]
}

In this example trace file, two steps (or actions) are defined. The first is representing the order request being sent from the Buyer role to the Seller role. The second is representing an order response being returned from the Seller role to the Buyer role. The message component defined the operator, list of parameter types, and list of parameter values. The values are currently optional - however once assertions are supported, the value will need to be provided.

The simulations section defines a list of simulations. Each simulation defined an optional name, and a map of role names to role simulators.

In this example, the only role simulator type used is MonitorRoleSimulator which uses the Scribble monitor to verify that the message transfers defined in the trace conform to the Scribble protocol identified by the module, role and protocol.

To perform a simulation from within your own application, you need to perform the following steps:

// Create a locator that can be used to load the scribble modules and any associated resources
org.scribble.resources.ResourceLocator locator=new org.scribble.resources.DirectoryResourceLocator(...);

// Build or load the trace (e.g. deserialize the JSON representation)
org.scribble.trace.model.Trace trace=...;

// Create a context using the locator
org.scribble.trace.simulation.SimulatorContext context=new org.scribble.trace.simulation.DefaultSimulatorContext(locator);

// Create the simulator
org.scribble.trace.simulation.Simulator simulator=new org.scribble.trace.simulation.Simulator();

// Instantiate an implementation of the listener interface, to be informed when steps are simulated
// successfully or unsuccessfully
org.scribble.trace.simulation.SimulationListener l=...;

// Add the listener to the simulator
simulator.addSimulationListener(l);

try {
	// Simulate the trace
	simulator.simulate(context, trace);
} catch (Exception e) {
	...
}

// Unregister the listener
simulator.removeSimulationListener(l);