SOFA Behavior Protocol Example

This example demonstrates the usage of the behavior description for SOFA components. The example is an extension of the logdemo example. This document provides a brief overview how to set-up a SOFAnode and start the modified logdemo application. For clarity, this demo is named protodemo.

The full source code of protodemo as well as its ready-to-run compiled form is available in the binary distribution of the SOFA PROTOTYPE implementation. After successful installation of the distribution, this demo application is immediately ready to run.

Figure 1. Protodemo application structure

Protodemo structure

Behavior protocols in CDL description

The CDL description of protodemo enhances the interface and frame specifications by behavior protocols
[BP]. For example, the behavior protocol of LogInterface declares, that the log method can be invoked only sequentially:

interface LogInterface {
   void log(in string number);
   
   protocol:
      log*
};

A frame protocol describe the behavior of a component as a black box. For example, the following description specifies, that the LoggingWorker frame should log any operation using the Log requires-interface.

frame LoggingWorker {
        provides:
	  WorkInterface Work;
        requires:
          LogInterface Log;
	  
	protocol:
	  !Log.log; 
	  ?Work.start{ !Log.log } ; 
	  ?Work.doit{ !Log.log }* ; 
	  ?Work.finish{ !Log.log }; 
	  !Log.log
      };

Note: If the CDL specification contains behavior protocol, the CDL compiler should be invoked using the -t option as follows:

$ cdlc -t protodemo.cdl

The compiler will inform you about the results of protocol conformance tests [BP].

Steps for executing of the protodemo

The commands used in the following text suppose that the bin directories of JDK and the SOFA distribution are included in the PATH environment variable. The executables in the bin directory of the SOFA distribution are written in the Perl; on UNIX-like machines it can be executed directly, on Windows machines it can be executed in the form perl nameOfTheScript argumentsOfTheScript ... - this way is presented in the following examples, it suppose the perl executable in your PATH variable and the bin directory of the SOFA distribution as your current working directory. If you are using the Active Perl distribution for Windows, you can use the program pl2bat to create batch files for launching perl scripts.

Run rmiregistry.

The rmiregistry is part of the JDK. It starts a remote object registry (for JAVA RMI) on the specified port on the current host. The registry default port is 1099 (the SOFA default configuration assume the port 2000). The rmiregistry command produces no output and is typically run in the background. The rmiregistry must not have the CLASSPATH environment variable set.

Starting rmiregistry on UNIX-like machines:
```
$ unset CLASSPATH
$ rmiregistry 2000 &
```
Starting rmiregistry on Windows machines:
```
C:\> set CLASSPATH=
C:\> start rmiregistry 2000
```
Run orbd.

The orbd is part of the JDK. It is used to enable clients to transparently locate and invoke objects on servers in the CORBA environment. You must provide the port number where the orbd will listen for incoming requests (the SOFA default configuration assume the port 2001). The orbd command produces no output and is typically run in the background.

Starting orbd on UNIX-like machines:
```
$ orbd -ORBInitialPort 2001 &
```
Starting orbd on Windows machines:
```
C:\> start orbd -ORBInitialPort 2001
```
Run TIR.

TIR (Type Information Repository) is part of the SOFA distribution. TIR serves as a storage for component's specifications. The command tir produce output with information about launching progress.

Starting TIR on UNIX-like machines:
```
$ tir &
```
Starting TIR on Windows machines:
```
C:\> start perl tir
```
Run the deployment dock registry.

The deployment dock registry is part of the SOFA distribution. It is used to enable locate the SOFA deployment docks. The produced output in the case of successful launching is DeplDockRegistry is running.

Starting deployment dock registry on UNIX-like machines:
```
$ ddockreg &
```
Starting deployment dock registry on Windows machines:
```
C:\> start perl ddockreg
```
Run the deployment dock.

The deployment dock is part of the SOFA distribution. It is the basic entity of SOFA runtime environment. The produced output in the case of successful launching is DeplDock NameOfDock is registered and running.

Starting deployment dock on UNIX-like machines:
```
$ ddock NameOfDock
```
Starting deployment dock on Windows machines:
```
C:\> perl ddock NameOfDock
```
Generate the specfile for the application.

On UNIX-like machines:
```
$ genspecfile ::CUNI::SOFA::demos::protodemo::loggingworker[0.0.1] nameOfGeneratedSpecFile
```
On Windows machines:
```
C:\> perl genspecfile ::CUNI::SOFA::demos::protodemo::loggingworker[0.0.1] nameOfGeneratedSpecFile
```
In the specfile, you can change the middleware used in the connector and/or specify, how the application should be distributed over the deployment docks. For now, do not change anything, i.e. the connector will be local and all components of the application will be launched in the single deployment dock.

Note: If you set up the components to be launched in several docks, you must run all docks.
Prepare application for launching.

On UNIX-like machines:
```
$ makeAppl nameOfGeneratedSpecFile.ssf
```
On Windows machines:
```
C:\> perl makeAppl nameOfGeneratedSpecFile.ssf
```
You can see how the connector is generated (meaning of the output).
Run SOFA application (in this case application protodemo).
The SOFA applications are launched by command lanchAppl, which is part of the SOFA distribution. It takes two arguments: 1st the full name of the application, 2nd name of the deployment dock in which the application should be launched. The command produce output with information about launching progress.
Launching application on UNIX-like machines:
```
$ launchAppl ::CUNI::SOFA::demos::protodemo::loggingworker[0.0.1] NameOfDock
```
Launching application on Windows machines:
```
C:\> perl launchAppl ::CUNI::SOFA::demos::protodemo::loggingworker[0.0.1] NameOfDock
```

Source code of the protodemo application

CDL description, provided by the developer:

protodemo.cdl

References

[BP] Plasil, F., Visnovsky, S.: Behavior Protocols for Software Components, IEEE Transactions on Software Engineering, vol. 28, no. 11, Nov 2002