jcsp.lang
Class TaggedProtocol

java.lang.Object
  |
  +--jcsp.lang.TaggedProtocol

Direct Known Subclasses:

GraphicsCommand, GraphicsProtocol

public class TaggedProtocol

extends Object

TaggedProtocol is the base class for messages carrying an occam2-like tagged (CASE) protocol over JCSP channels.

Example

Protocol Definition

SampleProtocol illustrates one approach to the passing of different information structures across the same JCSP channel. It corresponds to the tagged (CASE) PROTOCOL of occam2.1. The example was invented by Rick Beton (of Roke Manor Research Ltd.):

 PROTOCOL String IS BYTE::[]BYTE:  -- slight licence here!
 
 DATA TYPE Complex32
   RECORD
     REAL32 real, imag:
 :
 
 PROTOCOL SampleProtocol
   CASE
     NOTHING.IN.PARTICULAR
     STRING; String
     INTEGER; INT
     COMPLEX; Complex32
     BOO.TO.A.GOOSE
 :
 

This corresponds to the (JCSP) Java declaration:

 public class SampleProtocol {
 
   public static final int NOTHING_IN_PARTICULAR = 0;
   public static final int                STRING = 1;
   public static final int               INTEGER = 2;
   public static final int               COMPLEX = 3;
   public static final int        BOO_TO_A_GOOSE = 4;
 
   static public class NothingInParticular extends TaggedProtocol {
     public NothingInParticular () {
       super (NOTHING_IN_PARTICULAR);
     }
   }
 
   static public class String extends TaggedProtocol {
     public final java.lang.String string;
     public String (final java.lang.String string) {
       super (STRING);
       this.string = string;
     }
   }
 
   static public class Integer extends TaggedProtocol {
     public final int value;
     public Integer (final int value) {
       super (INTEGER);
       this.value = value;
     }
   }
 
   static public class Complex extends TaggedProtocol {
     public final float real;
     public final float imag;
     public Complex (final float real, final float imag) {
       super (COMPLEX);
       this.real = real;
       this.imag = imag;
     }
   }
 
   static public class BooToAGoose extends TaggedProtocol {
     public BooToAGoose () {
       super (BOO_TO_A_GOOSE);
     }
   } 
 
 }
 

The emphasis in the above definition is security. The protocol variants hold only immutable data (whose transmission, therefore, can never lead to race hazards). Secondly, it is impossible for the user of the protocol to set up an incorrect tag or misinterpret a correct one without raising an exception.

Protocol Use

This example has a simple pair of CSProcesses communicating over a channel using the SampleProtocol.

First, here is the occam2.1 version. The network is defined (and started) by:

 CHAN OF SampleProtocol c:
 
 PAR
   Producer (c)
   Consumer (c, screen)
 

where:

 PROC Producer (CHAN OF SampleProtocol out)
 
   VAL []BYTE m1 IS "Hello World ...":
   VAL []BYTE m2 IS "Goodbye World ...":
 
   SEQ
     out ! NOTHING.IN.PARTICULAR
     out ! STRING; (BYTE SIZE m1)::m1
     out ! INTEGER; 42
     out ! NOTHING.IN.PARTICULAR
     out ! COMPLEX; [3.1416, 0.7071]
     out ! STRING; (BYTE SIZE m2)::m2
     out ! BOO.TO.A.GOOSE
 
 :
 

and where:

 PROC Consumer (CHAN OF SampleProtocol in, CHAN OF BYTE screen)
 
   INITIAL BOOL running IS TRUE:
 
   WHILE running
     in ? CASE
       NOTHING.IN.PARTICULAR
         out.string ("==> NothingInParticular happening ...*c*n", 0, screen)
       BYTE size:
       [255]BYTE s:
       STRING; size::s
         SEQ
           out.string ("==> *"", 0, screen)
           out.string ([s FOR INT size], 0, screen)
           out.string ("*"*c*n", 0, screen)
       INT i:
       INTEGER; i
         SEQ
           out.string ("==> ", 0, screen)
           out.number (i, 0, screen)
           out.string ("*c*n", 0, screen)
       Complex32 c:
       COMPLEX; c
         SEQ
           out.string ("==> [", 0, screen)
           out.real32 (c[real], 0, screen)
           out.string (", ", 0, screen)
           out.real32 (c[imag], 0, screen)
           out.string ("*c*n", 0, screen)
       BOO.TO.A.GOOSE
         SEQ
           out.string ("==> Waaaaaa!  You scared me!!  I'm off!!!", 0, screen)
           running := FALSE
 
 :
 

Here is the (JCSP) Java version. The network is defined (and started) by:

 final One2OneChannel c = new One2OneChannel ();
 
 new Parallel (
   new CSProcess[] { 
      new Producer (c),
      new Consumer (c)
    }
 ).run ();
 

where:

 import jcsp.lang.*;
 
 public class Producer implements CSProcess {
 
   private final ChannelOutput out;
 
   public Producer (ChannelOutput out) {
     this.out = out;
   }
 
   public void run() {
 
     out.write (new SampleProtocol.NothingInParticular ());
     out.write (new SampleProtocol.String ("Hello World ..."));
     out.write (new SampleProtocol.Integer (42));
     out.write (new SampleProtocol.NothingInParticular ());
     out.write (new SampleProtocol.Complex (3.1416f, 0.7071f));
     out.write (new SampleProtocol.String ("Goodbye World ..."));
     out.write (new SampleProtocol.BooToAGoose ());
 
   }
 
 }
 

and where:

 import jcsp.lang.*;
 
 public class Consumer implements CSProcess {
 
   private final ChannelInput in;
 
   public Consumer (ChannelInput in) {
     this.in = in;
   }
 
   public void run () {
 
     boolean running = true;
 
     while (running) {
 
       TaggedProtocol tp = (TaggedProtocol) in.read ();
 
       switch (tp.tag) {
          case SampleProtocol.NOTHING_IN_PARTICULAR:
            System.out.println ("==> NothingInParticular happening ...");
          break;
          case SampleProtocol.STRING:
            SampleProtocol.String sms = (SampleProtocol.String) tp;
            System.out.println ("==> \"" + sms.string + "\"");
          break;
          case SampleProtocol.INTEGER:
            SampleProtocol.Integer smi = (SampleProtocol.Integer) tp;
            System.out.println ("==> " + smi.value);
          break;
          case SampleProtocol.COMPLEX:
            SampleProtocol.Complex smc = (SampleProtocol.Complex) tp;
            System.out.println ("==> [" + smc.real + ", " + smc.imag + "]");
          break;
          case SampleProtocol.BOO_TO_A_GOOSE:
            System.out.println ("==> Waaaaaa!  You scared me!!  I'm off!!!");
            running = false;
          break;
       }
 
     }
 
   }
 
 }
 

Author:

P.H.Welch

Field Summary

int	tag This public tag is used by the receiving process to determine which variant of a tagged protocol has been received.

Constructor Summary

TaggedProtocol(int tag)
This super-constructor is invoked by the extending sub-class constructor.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

tag

public final int tag

This public tag is used by the receiving process to determine which variant of a tagged protocol has been received. See the above Consumer example (and the definition of its input channel's SampleProtocol).

Constructor Detail

TaggedProtocol

public TaggedProtocol(int tag)

This super-constructor is invoked by the extending sub-class constructor. It should be passed a tag that is unique for the tagged protocol for which that sub-class is one variant. See the above SampleProtocol (and its use in Producer and Consumer).