Chapter 1. Protocol

This section explains how to make use of the Scribble Java tools to parse, validate and project a Scribble protocol. The following sections of this document explain how applications can then make use of these validated (and potentially projected) protocols to perform further tasks, such as monitoring message exchanges to ensure they conform to a defined protocol, or simulating message traces against endpoint simulators.

The Java tools make use of maven to store its artifacts (i.e. jars). These are associated with the group id org.scribble and the artifact id scribble-<component>, where the <component> is the individual area represented by the artifact. As well as there being an artifact per component of the tooling, there is an additional scribble-core artifact that contains items shared by all of the components.

1.1. Common Components (maven artifact id scribble-core)

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

1.1.1. Issue Logging

Whenever a component needs to perform processing on the protocol, to identify parsing, validation or projection issues, then the component will use the org.scribble.logging.IssueLogger to report any errors, warnings or other general information.

As part of the core artifact there is a org.scribble.logging.ConsoleIssueLogger implementation that reports any issues to the console, however an application is free to provide its own implementation. For example, the Eclipse tooling contains an implementation that converts the issues into Eclipse markers for reporting in the Marker or Problems views.

1.1.2. Context

The org.scribble.context package contains the following components that may be used with various protocol processing capabilities:

Module Loader

The org.scribble.context.ModuleLoader interface is used during a variety of processing stages, e.g. parsing, validation, monitoring, etc. It is responsible for retrieving a org.scribble.model.Module object model associated with a fully qualified module name.

There is a default implementation of the module loader org.scribble.context.DefaultModuleLoader that simply provides a caching capability for loaded modules. It is expected that a derived loader implementation will be provided, that will leverage the caching capability of the default implementation, but will provide the environment specific knowledge of how to obtain the modules. One such concrete implementation is org.scribble.parser.ProtocolModuleLoader which can be found in the scribble-parser component.

Module Context

The module context is responsible for providing support services to any processing that is occuring on a particular module. The focus of a particular module context instance will be an individual org.scribble.model.Module instance. Based on the definitions contained within that module instance, an application can request access to members, either within that module, or in an associated module (identified by a fully qualified name).

1.1.3. Resources

Within the org.scribble.resources package is contained classes/interfaces to provide support for locating and loading resources. These capabilities can be used to load modules, as well as any other appropriate resources used during parsing, validation or further stages.

1.1.4. Protocol Model

The model contains the general module components, as well as the specfic components to represent the local and global variations of the Scribble protocol.

The top level model component is org.scribble.model.Module.

1.2. Parsing (artifact id scribble-parser)

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:

the resource, containing the text based scribble protocol description
the loader, to load any additional modules (or potentially other resources) that may be required to support the parsing of the module
the logger, to report any issues that arise from parsing the protocol description

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.

1.3. Validating (artifact id scribble-validation)

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.

1.4. Projection (artifact id scribble-projection)

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.