Package org.jcsp.lang

# Class TaggedProtocol

java.lang.Object
org.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 = Channel.one2one ();

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

where:

     import org.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 org.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

Fields
Modifier and Type
Field
Description
`final int`
`tag`
This public tag is used by the receiving process to determine which variant of a tagged protocol has been received.

## Constructor Summary

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

## Method Summary

### Methods inherited from class java.lang.Object

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

## Field Details

### 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 Details

### 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).