JBoss.orgCommunity Documentation

Scribble 2.0

Protocol Guide


1. Overview
2. Protocol Constructs
2.1. Protocol Definition
2.2. Interaction
2.3. Sequence
2.4. Choice
2.5. Parallel
2.6. Repetition
2.7. Recursion
2.8. Global Escape
2.9. Composition
3. Examples
3.1. Buyer Seller Protocol
3.2. Credit Check Protocol
3.3. Purchasing Goods Conversation

Scribble is a simple text based language for describing interactions between multiple parties in the form of a Protocol.

The Protocol notation is intended to provide an abstract description of the communication behaviour, with addtional optional layers being used to describe assertions and other governance related information.

In the world of programming languages, the measure of the simplicity of a language is based on its representation of a simple 'hello world' example. The Scribble Protocol representation of such an example would be:

The notation will be explained in more detail in this guide, but basically the protocol is named 'HelloWorld', and describes the communication behaviour between two roles (or parties). A single interaction has been defined, sending a message of type 'Hello' from role 'You' to role 'World'.

In the following chapter we will explore the main constructs of the protocol notation. Then we will explore a range of examples, before concluding with a brief overview of some more advanced constructs that are still under development.

The protocol definition is comprised of a:

The syntax for the process definition is:

The import statement is used to define a type that will be used within the protocol definition. When referenced in the protocol, the type is known by a local name (or alias). If we want to be able to monitor, or use the protocol definition in any other 'real world' situation, then we need to bind the concrete type information to this alias.

The import statement can optionally define a type system associated with the imported type. For example, this could be 'java' if referring to a Java class or interface, or 'xsdtype'/ 'xsdelem' for an XSD type or element.

The import can optionally specify the location of the type information, by specifying the 'from' keyword followed by a string literal with type system specific location information.

Within the type information, we can identify one or more specific data types, followed by the 'as' keyword and then the name of the type alias.

In its simpliest form, the import can just define the type name, which will be represented without any type system specific information. The next level can introduce a type specific 'data type' value. Finally the most complete version will include the location of the type information.

Following the import statements is the declaration of the protocol unit itself. This defines the name of the protocol and whether it is located at a particular role.

The following represents a 'global' protocol example:

This example shows three variations of the import statement. The first importing a single type based on a name, without any concrete type information being bound.

The second importing a particular XSD schema, from a schema location, and referring two specific types within the schema. The first being an XSD type, known by the qualified name {http://www.acme.org/Purchasing}Order and locally referred to using the alias Order. The second being an XSD element, known by the qualified name {http://www.acme.org/Purchasing}Quote and locally referred to using the alias Quote.

The third import statement shows the case where two Java classes are bound to local aliases. The Java package is specified within the 'from' clause, and the class name is defined prior to the 'as' keyword in each case.

The global protocol is then defined, named as PurchaseGoods. This is a global protocol because it does not specify a particular role at which the definition is located.

A local protocol variation would be:

This local representation of the protocol defines the behaviour from the Buyer role's perspective. That is why the roles declared within the protocol unit only include the Seller, as this is the role with which the Buyer is going to communicate.

The choice construct represents a set of mutually exclusive paths triggered by different interactions that could occur between two roles. One of the roles will be the decision maker, initiating the interaction, and the other role will be the recipient, reacting to the specific message received.

The syntax for the choice construct is:

For example,

For example,

Another example is,

In this example, the first choice path defines a message signature with only a label (or operation name). The significance of this is that, depending upon the message transport being used, this label may not be carried from the Broker to the Buyer. The possible scenarios are:

This chapter presents some examples using the protocol notation.