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

AIOCJ Presentation Paper: Dalla Preda, M., Giallorenzo, S., Lanese, I., Mauro, J., & Gabbrielli, M. (2014). AIOCJ: A choreographic framework for safe adaptive distributed applications . In Software Language Engineering (pp. 161-170). Springer International Publishing.
Foundational Theory: Dalla Preda, M., Gabbrielli, M., Giallorenzo, S., Lanese, I., & Mauro, J. (2015, June). Dynamic Choreographies. In Coordination Models and Languages (pp. 67-82). Springer International Publishing.
Comprehensive Journal Paper: Dalla Preda, M., Giallorenzo, S., Lanese, I., Mauro, J., & Gabbrielli, M. (2016) Dynamic Choreographies: Theory and Implementation. Accepted at Logical Methods in Computer Science.
AIOCJ Tutorial: Giallorenzo, S., Lanese, I., Mauro, J., & Gabbrielli, M. (2016) Programming Adaptive Microservice Applications: an AIOCJ Tutorial. Behavioural Types: from Theory to Tools.
Software development process: Giallorenzo, S., Lanese, I., & Russo, D. (2018) ChIP: A Choreographic Integration Process. Accepted at CoopIS 2018, OTM 2018.
Extension with new Roles in adaptation rules: Gabbrielli, M., Giallorenzo, S., Lanese, I., & Mauro, J. (2019). Guess Who's Coming: Runtime Inclusion of Participants in Choreographies. The Art of Modelling Computational Systems: A Journey from Logic and Concurrency to Security and Privacy.
Full AIOCJ Syntax

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

The Java Developer Kit installed in order to install Jolie. The Java Runtime Environment installed in order to execute Jolie, Eclipse and Xtext. Both can be retrieved at http://www.oracle.com/technetwork/java/javase/downloads/index.html;
Jolie, please refer to http://www.jolie-lang.org/?top_menu=downloads for the comprehensive instructions for installing the Jolie interpreter;
Since version 1.8, the Jolie interpreter comes with an implicit timeout for request-response operations, which might make AIOCJ-projected programs terminate with a timeout error. Our suggestion for quickly trying AIOCJ programs is to use version 1.7.1 of the Jolie interpreter. Later versions of the Jolie interpreter can be used, launching the interpreter with the option --responseTimeout 120000.
Eclipse Xtext 4.3. The program and the instructions for installation are available at http://www.eclipse.org/Xtext/download.html;
Itemis also offers a repository of Eclipse releases with Xtext already installed.

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:

Appointment program | AIOC Adaptation rules External Services

AIOCJ: A Choreographic Framework for Safe Adaptive Distributed Applications

Tutorial choreographies provided in the book chapter "Programming Adaptive Microservice Systems: an AIOCJ Tutorial"

Buyer choreography | AIOC Adaptation rules External services

Distributed adaptive document system | AIOC Adaptation rules External services
- Distributed adaptive document system with dirty read control | Adaptation rules
(taken from R. Pawlak et al. JAC: an aspect-based distributed dynamic framework.)

Adaptive conferencing application with support for secure communication | AIOC Adaptation rules
(taken from Z. Yang et al. An aspect-oriented approach to dynamic adaptation.)

Adaptive context-oriented chat: ContextChat | AIOC Adaptation rules
(taken from Salvaneschi, G. et al. ContextErlang: Introducing Context-oriented Programming in the Actor Model)

Illustrative example of the ChIP integration process | Choreography, Projection, and Mock-up Services
Example of adaptation with external roles from the paper Guess Who’s Coming: Runtime Inclusion of Participants in Choreographies | Choreography, Adaptation Rule, Projection, and Mock-up Services

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" ;
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 . 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 bash 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.

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