AIOCJ

an open-source choreography language for developing correct adaptive distributed systems from a global viewpoint.


AIOCJ Language

AIOCJ is an open-source choreography programming language for developing adaptive systems. Choreography languages describe in a single view the global interaction among all entities (roles) in a system. Systems specified in AIOCJ benefit from this approach and are also deadlock-free by construction. Moreover, AIOCJ choreographies adapt. Through scopes the developer can specify which fragments of the interaction can change with respect to applicable rules, provided by a compliant repository. Rules are specified as AIOCJ choreographies and after the adaptation the system remains deadlock-free. AIOCJ choreographies can also make use of functions provided by external services (e.g., as done here).

AIOCJ provides a projection function. AIOCJ choreographies are projected into a set of separate programs that enact the specified interaction and can be distributed. Rules are projected into a distributable standalone repository.

Papers and References

Hello World! Example

Let us write a first example of an adaptable choreography written in AIOCJ. u1 sends the message "Hello" to u2. The rule applies, as its matches with the property N.scope_name of the scope, and the result of the execution will display the message "Hello World!" to u2.

preamble {
 starter: u1
}

aioc {
 scope @u1{
   msg@u1 = "Hello"
 } prop { N.scope_name = "hello_world"};
 sendMsg: u1( msg ) -> u2( msg );
 r@u2 = show( msg )
}
rule {
 on { N.scope_name == "hello_world" }
 do {
  msg@u1 = "Hello World!" 
 }
}

For further details, please check out the AIOCJ Syntax.

Advanced Hello World!

On the previous example, we add iteration of adaptation and conditions on environmental variables in rules (prefixed by E) to better explain how to write several rules and check for their applicability at runtime. As in the previous example, u1 sends the message "Hello World" to u2. The whole choreography is enclosed by a while, controlled by u1.

preamble {
  starter: u1
}

aioc {
 continue@u1 = "y";
 while( continue == "y" )@u1{
  scope @u1 {
   msg@u1 = "Hello World"
  } prop { N.scope_name = "hello_world" };
  sendMsg: u1( msg ) -> u2( msg );
  {
   r@u2 = show( msg ) 
   | continue@u1 = getInput( "Continue? (y/n)" ) 
  }
 }
}
rule {
 on {
  N.scope_name == "hello_world" and 
  E.lang == "it" } 
 do {
  msg@u1 = "Ciao Mondo"
 }
}

rule {
 on {
  N.scope_name == "hello_world" and 
  E.lang == "fr" } 
 do {
  msg@u1 = "Bonjour le Monde"
 }
}

The last code block in the choreography (Lines 12-15) uses the parallel operator to show the msg to u2 and to ask for continuation to u1 at the same time. In AIOCJ, brackets define sub-choreographies. In this case, we employ this feature to define that the code at Lines 12-15 executes only after u1 sent to u2 the msg (Line 11). Without the brackets, the instruction at Line 14 would execute in parallel wrt the scope.

We define two rules (respectively Lines 1-8 and 10-17). They both satisfy the condition of the non-functional property scope_name of the scope. However, they differ on the condition of the environmental variable E.lang. Environment can change at runtime.

The current implementation of AIOCJ equips a program called environment that simulates the presence of an environment that can be queried for environmental variables. Such program is part of the adaptation middleware. Environmental variables can be set (at runtime) by interacting with the shell in which the service running. Back to our example, if we set a new environmental variable lang to the value it, the first rule applies. Likewise, if the set lang to fr, the second rule applies.

Installation

Requirements

Installation procedure

  • In Eclipse, click command link Help > Install New Software.... Deselect check box Group items by category and copy in the combo box Work With the site address http://www.cs.unibo.it/projects/jolie/aiocj/. The feature AIOC Language Plugin Feature should be visible in the frame of available software.

  • Check the box relative to the plugin. Click Next for requirement collection. Next again to confirm the install details. Select the radio button for accepting the License Agreement terms and click on Finish.

  • Eclipse will now install AIOCJ-ecl. At the end of the installation Eclipse will reboot and the plugin will be installed.

From now on, we will refer the launched Eclipse instance as AIOCJ-ecl.

Some examples of AIOCs and adaptation rules

We provide several examples of adaptable choreographies and rules for their adaptation:

Compiling AIOCs and rules

Compiling an AIOC

Once selected one example, let us project the AIOC first.

  • Create a New -> General -> Project in AIOCJ-ecl. Let us name it "Example";

  • create a new File (Right-click on the project -> Create new -> File) named "Example.ioc";

  • Xtext will recognize the extension ".ioc" and ask if we want to add the Xtext nature to the project. Confirm. The empty file, ready for edit, is now visible;

  • copy the content of the choreography and execute the projection by clicking on button "Jolie Endpoint Projection" Jolie Endpoint Projection Button;

  • the projection creates a folder named "epp_aioc" in the project. In case Eclipse does not show it, refresh the view in the package explorer. Alternatively, you can open the project folder following its path with a file manager.

Compiling a (set of) rule(s)

Similarly to AIOC projection, rule(s) projection requires the creation of a new file.

  • Create a new File named "ExampleRules.ioc" and copy the content of the rules relative to the chosen choreography into it;

  • project via "Jolie Endpoint Projection" button Jolie Endpoint Projection Button. The process creates a new folder named "epp_rules" containing the projected files.

Running an adaptive choreography

To ease testing the projected choreography locally, the projection creates several batch files that open a shell for each component of the choreography. The main batch script choreography_launcher.sh takes care of launching all other batch scripts in the proper order, i.e., the adaptation manager, the environment, the external services, the adaptation server, and the roles of the choreography. The script can be launched from a shell with the command sh choreography_launcher.sh. We give a brief description of the sub-scripts launched by the main script to ease customisation and help to understand the structure of AIOCJ programs.

  1. in the root folder of the project, the script mid_launcher.sh starts the adaptation manager and the environment services. Also, in the root folder the script service_launcher.sh can be customised to launch the external services used by the choreography. At Line 19 the list services contains the names of the Jolie services to be launched. E.g., if the compiled choreography uses services AService.ol and BService.ol, Line 19 will look like this services=( "AService.ol" "BService.ol" ). N.B. in order to use the provided script, the files of the services must be located in the root folder;

  2. in the folder epp_rules, the script rules_launcher.sh starts the adaptation server (launching this script is optional and necessary only if we want adaptation rules to be tested and applied to the projected scopes);

  3. in the folder epp_aioc, the script aioc_launcher.sh starts the starter role of the choreography. Then it waits for an input of the user to proceed with the execution of the roles of the choreography. Pressing [Enter] launches the last role, which begins the execution of the choreography.

Get the source code

AIOCJ is released under the GNU Lesser General Public License v2.1 and its sources are available on Github.