JBoss.orgCommunity Documentation

Chapter 2. Protocol Constructs

2.1. Protocol Definition
2.2. Interaction
2.3. Sequence
2.4. Choice
2.5. Repetition
2.6. Composition

2.1. Protocol Definition

The protocol definition is comprised of a:

The syntax for the process definition is: 

namespace <namespace> ";"

{ import <fully qualified type> [ "@" <URL> ] ";" }*

protocol <name> [ "@" <Participant> "{"
    .... ";"
"}"

The namespace can define a user specific hierarchy to organise protocol definitions. The separate parts of the hierarchy can be specified separated by '.'.

The import statement enables fully qualified types to be referenced within the protocol definition based on their local name. For example, the type my.scribble.type.Order could be imported into a protocol definition, and subsequently referenced based only on the local part of the fully qualified name, i.e. Order.

The types can represent any scribble type that needs to be referenced. This could be message types, exchanged as part of an interaction, or other protocol definitions.

The final part of the protocol definition is the declaration of the protocol unit itself. This defines the name of the protocol and whether it is located at a particular participant.

The following represents a 'global' protocol example: 

namespace my.scribble.examples;

import my.scribble.type.Order;
import my.scribble.type.Trade @ http://www.examples.org/types/Trade.xsd ;

protocol PurchaseGoods {
    participant Buyer, Seller;
    ....
}

The namespace can be any user defined scope. In this case it is my.scribble.examples.

This example shows two variations of the import statement. The first importing a single type based on its fully qualified name. The second importing a particular type, and also identifying a URL where more details about the type can be found.

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

A local protocol variation would be: 

protocol PurchaseGoods @ Buyer {
    participant Seller;
    ....
}

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

2.2. Interaction

Interactions in Scribble are based on two assumptions:

The syntax for the interaction is: 

<MessageSignature> [from <Participant>] [to <Participant>]

The following example shows a similar type of interaction as shown in the 'hello world' example. 

participant Customer, Supplier;
Order from Customer to Supplier;

In this sample, two participants are declared, with the interaction indicating that a message of type 'Order' will be sent from participant 'Customer' to participant 'Supplier'. 

placeOrder(Order) from Customer to Supplier;

This example demonstrates an alternative way for the exchanged message to be specified. In the first sample a message-style was used. In this sample, an RPC style has been used, specifying the operation name with type parameters. In this case, only a single typed parameter Order has been specified, but this could be a comma separated list of zero or more types.

2.3. Sequence

The sequence construct is a list of activities, separated by a semi-colon, such that each subsequent activity is only performed after the completion of the preceding activity. 

"{"
    { <Activity> ";" }*
"}"

where Activity<i> represents any protocol based activity or construct.

The following example shows a sequence of interactions. 

{
    Order from Buyer to Seller;
    Invoice from Seller to Buyer;
    Payment from Buyer to Seller;
    Confirmation from Seller to Buyer;
}

2.4. Choice

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

The syntax for the choice construct is: 

choice [from <Participant>] [to <Participant>] "{"
	when <MessageSignature> "{"
    	...
    "}"
	when <MessageSignature> "{"
    	...
    "}"
"}"

For example, 

CreditCheck from Seller to CreditAgency;

choice from CreditAgency to Seller {
    when CreditRefused {
    }
    when CreditOk {
    }
}

2.5. Repetition

The repeat construct represents the 'while' style loop. A decision will be made at one or more nominated participants. If more than one located participant is defined, then all of those participants must synchronize in their decision making, using some non-observable mechanism.

The first activity contains within the repetition construct must be initiated at one of the located participants associated with the construct.

The syntax for the repeat construct is: 

repeat "@" <Participant> { "," <Participant> }* "{"
    ...
"}"

The following example shows a repeat construct, located at the Buyer participant. This means that the Buyer will be responsible for deciding when to iterate, and when to terminate the repetition.

It also means that the initial activity (in this case interaction) defined within the repeat construct must be initiated by the Buyer. In this case, the Buyer is sending an Order message to the Seller. 

repeat @ Buyer {
    Order from Buyer to Seller;
    Invoice from Seller to Buyer;
}

2.6. Composition

Protocols can be defined in a modular way, with one protocol being able to compose another using the run construct.

The run construct composes another protocol in a synchronous manner. This means that the composed protocol will complete before any subsequent activity in the composing protocol can proceed.

There are two ways in which another protocol can be composed. These are:

The syntax for the run construct is: 

run <ProtocolName>"(" <CP1> = <P1> { "," <CPn> = <Pn> }* ")" "{"
    participant CP1 { "," CPn }* ";"
    ...
"}"

An example of the internal variation, using the run, is: 

participant Client, Supplier;
....
run PlaceOrder(Buyer = Client, Seller = Supplier);
....
protocol PlaceOrder {
    participant Buyer, Seller;
    ....
}

The external variation is similar to the internal variation above, except that the composed protocol definition (i.e. PlaceOrder in this case), would be stored in a separate definition. A run based external variation for the composing protocol would be: 

participant Client, Supplier;
....
run PlaceOrder(Buyer = Client, Seller = Supplier);