Make Agents Yourself

h1. Make Agents Yourself Tutorial

{{>toc}}

% TODO : exemple complet, clair et qui colle au code

%        ajouter utilisation objet commun à plusieurs composants (ou remplacé par un compo (Representation))

%        retirer code généré !

h2. Introduction

In this tutorial, we are going to see an introduction to MAY.

This tool was made to build application-specific models of agent and to generate dedicated framework providing them.

Such framework would then be usable to program agents compliant with the realised model of agent.

More specifically, a model of agent is realised by an architecture divided in two levels: "container" (the how), hidden to the user of the framework and "application" (the what) expression what the agent does.

These two levels links MuComponents together to form a MuArchitecture realising the model.

Furthermore, such agents have the possibility to self-adapt at runtime: currently, this means that a MuComponent is able to change the implementation of another MuComponent of the MuArchitecture.

In practice, these models are described with the help of the MuADL description language, and from this description, the Java code needed to implement the MuComponents is generated.

The MuArchitecture itself is generated and is directly usable by setting the implementation of its MuComponents.

This tool being experimental, several functionalities described are are subject to change in the future.

If possible, this will be stated in this document.

h3. Requirements

To use MAY, the _Eclipse IDE_ is needed.

It can be found at http://www.eclipse.org/.

h3. Installation

The installation is done from the _Software Update_ in _Eclipse_ by adding the following _Update Sites_:

<pre>

http://www.irit.fr/PERSONNEL/SMAC/noel/may/update/

http://oawbranch.pluginbuilder.org/releases/p2-updateSite/

</pre>

Choose to install _Make Agents Yourself_.

h3. Upgrades

When upgrades are available, just use the _Update_ feature of _Eclipse_.

h2. Typical Development Process of an Agent with MAY

As explained before, MAY is a tool usable to description MuArchitectures based on MuComponents to generate a framework that will be distributed to application developers.

Several phases in the development can be distinguished:

* Description of the MuComponents and MuArchitectures:

  * Create a MAY project

  * Describe the model with MuADL

  * Generate the corresponding Java code

* Implantation of the MuComponents with Java

* Implantation of a _Factory_ with Java

* Generation of the distributable framework in the form of a JAR file

The following sections will describe in detail these development phases.

We will see the tools MAY adds to _Eclipse_, a description of MuADL and some advice to develop an agent and its MuComponents.

h2. Added Tools to _Eclipse_

The tools proposed by MAY are the following:

* Creation of a MAY project

* Creation of a textual MuADL description file

* Generation of the corresponding code in Java

A graphical editor is currently being worked on.

h3. Creation of a Project

A MAY project is just a Java _Eclipse_ project with supplementary dependencies and a specific required directory named @src-gen@.

Create a new Java Project.

Add a source directory named @src-gen@.

Add the MuADL library corresponding to the version of the plugin (current is 0.11.0) that can be found at "this place":http://www.irit.fr/PERSONNEL/SMAC/noel/maven-repos/fr/irit/smac/muadl/muadl-impl/ as a JAR (_e.g._ @0.11.0/muadl-impl-0.11.0.jar@)

h3. Creation of a Textual MuADL Description File

The description of a model of agent is represented by a text file containing the description of MuComponents and MuArchitectures with MuADL (presented Sect.~\ref{muadl}).

The extension of these files is @muadlt@.

The editor features syntactic colouration, completion and validation of MuArchitectures.

To create a new MuADL file, go to _File_, _New_, _Others..._, _Make Agents Yourself_ category and choose _MuADL Text file_.

Follow the instructions.

h3. Generation of the corresponding code in Java

This action generates the classes required for the implementation of the MuComponents described in the MuADL file (the @QuasiComponent@), the class representing the mediator of the MuArchitecture and the class façade representing an agent compliant with the MuArchitecture.

To generate the corresponding code of a MuADL file (a file ending in @.muadlt@), do a right click on it and in the sub-menu _Make Agents Yourself_, choose _Generate QC and Architecture_.

The generated code will be in the @src-gen@ directory.

It is important to notice that the content of this directory must never be modified.

h2. MuADL: Description Language for Agent Architectures

As said before, MAY, using MuADL, make possible to describe:

* MuComponents that: \todo{MuADL does not permit to specify how they will be implemented (no information of the constructors, the class attributes or private methods)}

  * Provides operations

  * Requires (from the MuArchitecture) operations

  * Requires (from the MuArchitecture) the possibility to change other MuComponents

  * Have a state that must be persisted by the MuArchitecture when their implementation is changed at runtime

* MuArchitectures containing MuComponents and divided in two levels

* Datatypes use by MuComponents and corresponding to Java types (classes or interfaces).

We detail here how to describe these elements.

h3. DataTypes

To refer to Java types, we give them a name in the MuADL file.

The syntax is as following:

<pre>

DataType AliasLocal : package.NomClass

DataType AliasLocal : package.NomClass<Generique>

DataType AliasLocal : package.NomClass<package.Generique>

// examples

DataType String : String

DataType Int : int

DataType Msg : my.package.Msg

DataType ListString : java.util.List<String>

DataType MailBox : java.util.List<my.package.Msg>

</pre>

\todo{Currently, no verification is done on the existence of these classes}

It is important to understand that DataTypes are just aliases, they can't be used inside generics parameters.

h3. MuComponents

Elements of a MuComponent :

* A name

* Provided operations (@provided@)

* Required operations (@required@)

* Attributes that must be persisted between runtime replacement of implementations (@persistent@)

* A set of MuComponents whose implementation could be changed at runtime \todo{This point is likely to change in the future} (@change@)

The MuComponents operations are similar to Java methods: they have a name, ordered typed parameters and a return type.

To refer to a method, it is only needed to know its name, its ordered parameter types and its return type.

An example of MuComponent :

<pre>

MuComponent Message {

  package a.test.package

  provided send(mess : String)

  provided receive() : String

  persistent mailbox : MailBox

  required do(String) : Int

  change LifeCycle

}

</pre>

h3. MuArchitectures

A MuArchitecture have:

* A name

* A set of MuComponents in the container level (@container@)

* A set of MuComponents in the application level (@application@)

* A set of visibility modifiers on th MuComponents operations (@visibility@)

The MuComponents can be specified as changeable (with @changeable@) by other MuComponents.

MuComponents can only change MuComponents of the same level.

By default, a MuComponent operation of the application level is visible by every MuComponents of the MuArchitecture, and a MuComponent operation of the container level is only visible by the MuComponents of the container level.

This fact can be changed by specifying (with @application@ visibility) that an operation of the container level is visible in the application level.

An operation of the MuArchitecture can be specified as being available from outside of the agent (with @external@ \todo{This is susceptible to change in the future}).

An example of MuArchitecture :

<pre>

MuArchitecture MyAgent {

  package another.test.package

  container {

    changeable LifeCycle

    Message

  }

  application {

    Behavior

  }

  visibility {

    external Message.send(String)

    application Message.receive() : String

  }

}

</pre>

Notice that :

* If a MuComponent @A@ requires an operation @0@, then a MuComponent providing @0@ must be present in the MuArchitecture.

* Requirements are only validated in the MuArchitecture.

* Two MuComponents can't provide the same operation.

h3. Complementary Informations

MuADL allows for comments :

<pre>

  // a comment

  /*

  a multi-line

  comment

  */

</pre>

h2. Implantation of MuComponents, use of MuArchitectures and Framework Distribution

After the Java code from a MuADL file was generated (see \ref{generation}), MuComponents implementation and MuArchitectures instantiation is possible.

The generation result in a set of Java classes situated in the @src-gen@ directory.

To implement MuComponents, we will write Java classes (typically in the @src@ directory) that extends some of these generated classes.

h3. MuComponents Implementations

For each MuComponent @X@ defined in the MuADL file, MAY generates a class @QuasiComponentX@ and a class @AdapterX@.

The first must be extended to implement @X@.

For example, there is the two generated classes for a component @LifeCyle@:

<pre>

public abstract class QuasiComponentLifeCycle

    extends QuasiComponent<AdapterLifeCycle>  {

  abstract public void suicide();

}

</pre>

<pre>

public interface AdapterLifeCycle extends Adapter {

  public void cycle(java.lang.String arg0);

  public java.lang.String receive();

}

</pre>

Thus, by extending @QuasiComponentLifeCycle@, one can use the required methods of the MuComponent by using the architecture through the method @this.architecture()@.

There is an example of this MuComponent :

<pre>

public class LifeCycle extends QuasiComponentLifeCycle {

  private boolean alive = true;

  @Override

  public void start() {

    Runnable me = new Runnable() {

      public void run() {

        while (alive) {

          String msg = architecture().receive();

          architecture().cycle(msg);

        }

      }

    };

    new Thread(me).start();

  }

  public void suicide() {

    alive = false;

  }

}

</pre>

The important points to notice are:

* A method @void start()@ is present to execute instructions at the start of the agent

* @this.architecture()@ gives access to required methods through the MuArchitecture

There is an example of a generated MuComponent with a persistent state:

<pre>

public abstract class QuasiComponentMessage

    extends QuasiComponent<AdapterMessage>

    implements WithPersistentState<PersistentStateMessage> {

  abstract public void send(java.lang.String message);

  abstract public java.lang.String receive();

}

</pre>

<pre>

public interface AdapterMessage extends Adapter {}

</pre>

When implementing it, one has access to the methods needed for the handling of the persistent state (automatically called by the architecture if the MuComponent implementation is changed at runtime).

There is an example of implementation for this MuComponent:

<pre>

public class Message extends QuasiComponentMessage {

  private ArrayBlockingQueue<String> messageBox =

    new ArrayBlockingQueue<String>(100);

  public void send(String message) {

    try {

      messageBox.put(message);

    } catch (InterruptedException e) {

      e.printStackTrace();

    }

  }

  public PersistentStateMessage getPersistentState() {

    return new PersistentStateMessage(

                new ArrayList<String>(messageBox)

           );

  }

  public void setPersistentState(PersistentStateMessage state) {

    messageBox =

      new ArrayBlockingQueue<String>(10, false, state.messageBox);

    System.out.println("Message Component started with "+

                        messageBox.size()+ " messages");

  }

  public String receive() {

    try {

      return messageBox.take();

    } catch (InterruptedException e) {

      e.printStackTrace();

      return "";

    }

  }

}

</pre>

Notice that we use an object of type @PersistentStateMessage@ to store and read the persistent state.

There is an example of a generated MuComponent changing another MuComponent implementation:

<pre>

public abstract class QuasiComponentAdaptation

    extends QuasiComponent<AdapterAdaptation>  {

  abstract public void adapt();

}

</pre>

<pre>

public interface AdapterAdaptation extends Adapter {

  public void change(QuasiComponentMessage _comp);

}

</pre>

Notice that a @void change(QuasiComponentMessage _comp)@ method is present to give access to the replacement functionalities of the MuArchitecture.

There is an example of implementation of this MuComponent:

<pre>

public class Adaptation extends QuasiComponentAdaptation {

  public void adapt() {

    architecture().change(new Message());

  }

}

</pre>

We can also see here for the first time the instantiation of a MuComponent.

When calling @change(...)@, the MuArchitecture will get the current state of @Message@ and will inject it in the new implementation with the methods we defined previously in @Message@.

h3. MuArchitecture Use

To use a MuArchitecture is to create an agent complying to this MuArchitecture by instantiating each of its MuComponents.

For this, the generated code of a MuArchitecture @X@ consists into 2 classes: @XMediator@ and @X@.

The first one is the implementation of the MuArchitecture itself, and the second one is a façade providing the external methods of the agent \todo{This will change in the future.}.

Thus, to create an agent compliant with a MuArchitecture @SimpleAgent@ with 4 MuComponents @Adaptation@, @Message@, @LifeCycle@ and @Behavior@ is done like this:

<pre>

  SimpleAgent agent1 = new SimpleAgent(

                          new Message(),

                          new LifeCycle(),

                          new Adaptation(),

                          new Behavior());

  agent1.start();

</pre>

Notice the call to @start()@ that starts each of the MuComponents and thus the agent.

h3. _Factory_

One of the objectives of MAY being to reduce the development effort by distributing models of agents ready to use, it is necessary to be able to provide partially instantiated MuArchitecture where some of the MuComponents implementation are already fixed.

These will then be directly usable by users by choosing the remaining MuComponent implementations.

This is done by using a _Factory_, which currently must be built by hand.

A factory is only a class providing one (or several) static methods instantiating some MuComponents and an agent.

For example:

<pre>

public class MySimpleAgent {

  public static SimpleAgent create(QuasiComponentBehavior behavior) {

    SimpleAgent agent = new SimpleAgent(new Message(),

                                        new LifeCycle(),

                                        new Adaptation(),

                                        behavior);

    agent.start();

    return agent;

  }

}

</pre>

Thus, to create an agent, one just need to know @MySimpleAgent.create(...)@.

For example:

<pre>

public class Main {

  public static void main(String[] args) {

    SimpleAgent agent1 = create(new Behavior2("agent1"));

    SimpleAgent agent2 = create(new Behavior("agent2", agent1));

    agent2.send("hello");

  }

}

</pre>

h3. Framework Distribution

The created classes in the previous sections form a framework usable by a user of the model of agent to create agents.

Delivering them to such an user is to export the _Eclipse_ project as a JAR using its export facilities:

right-click on the project, choose _Export..._, in the _Java_ category, choose _JAR File_ and follow the instructions.

The resulting JAR file will only need the _fr.irit.smac.muadl.impl_X.X.X.jar_ file available of the MAY website.

For example they can both be added to a classic _Eclipse_ Java project as dependencies.