Make Agents Yourself

h1. SpeADL Full Reference

{{>toc}}

In SpeADL, a set of abstractions are provided to describe [[SpeADL Minus Reference|typical component-oriented architectures]].

On top of these, SpeADL introduces additional abstractions that complete them in order to describe dynamic architectures, in particular for Multi-Agent Systems.

The motivations behind these abstractions are fully discussed in the "Ph.D. thesis":http://www.irit.fr/~Victor.Noel/PhD/Dissertation that led to the creation of MAY, here we stay at the user level.

The main idea with these abstractions is to define software components, called ecosystems, that are able to dynamically create other software components, called species, and to link such components to their ecosystem in a safe and controlled manner.

For example, one could define a Bank component containing a Database and that creates Account component which themselves requires access to the Database.

Or one could define a MAS component that creates Agent components (themselves architectured as desired) connected to simulated situated entities living in a common 2D environment.

With these abstractions, one can actually implement its own interconnection mechanism between the dynamically created components and their creating component.

This enables for example to cleanly and easily implement any needed interaction mechanism in a MAS when there exists no agent-oriented framework proposing it, to develop domain-specific relations between the agents and their environment or more generally to easily separate concerns (the agents architecture, the simulated agents, the communication) by composing them while explicitly taking into account the 1..N relation existing between an ecosystem and its species.

h2. SpeADL⁻

It is needed to understand the content of the [[SpeADL Minus Reference|SpeADL⁻ Reference Guide]] before reading the current document.

h2. Ecosystem and Species Definition

From an external point of view, an ecosystem is exactly similar to a component: it has provided ports that can be accessed and required ports that must be connected.

It has a name, can have type parameters and be a specialisation of another component.

It has an implementation in Java, it can be used as a part of another component (or ecosystem) or instantiated directly if it has no required ports.

Its only specificity is that it can contain what is called species, a special type of component class that can only be defined in an ecosystem.

Actually, a component is just an ecosystem without any species.

Species are to ecosystems what Java non-static inner classes are to Java classes: they are components class that can only be instantiated from within an ecosystem instance.

Because of this particular relation to ecosystems, species can access elements inside the ecosystem in two different ways:

* Directly to the parts and ports of the ecosystem.

* Indirectly through a special construct called _uses_ that enables to take into account the dynamic creation aspects of the species to:

** Build tailored ecosystem-species relations.

** Build tailored inter-species relations mediated by the ecosystem.

Uses are discussed [[SpeADL Full Reference#The Use Abstraction|below]].

h3. Keywords

An ecosystem class definition is declared with the keyword *ecosystem* followed by a name, optional type parameters and optional specialization.

Provided and required ports can be declared as with normal component classes with the keywords *provides* and *requires*.

Parts can be declared as with normal component classes with the keyword *part*.

A part can reference a typical component or an ecosystem.

A species is declared inside an ecosystem with the keyword *species* followed by a name starting with a capital.

It can't have type parameters but follows those of its ecosystem, and cannot specialise another component.

A species can have parameters (for initialisation) inbetween *( * and * )* and separated by *, *: they are of the form _name: Type, name2: Type2_.

Provided and required ports can be declared as with normal component classes with the keywords *provides* and *requires*.

Parts can be declared as with normal component classes with the keyword *part*.

Uses are declared with the keyword *use* as discussed [[SpeADL Full Reference#The Use Abstraction|below]].

h3. Details

Declaring a species means that an instance of the ecosystem  containing it will be able to create new instances of the species at runtime.

Such species will be considered strongly linked to the containing ecosystem instance that created them: this is a thus 1..N relation.

The bindings of the parts can point to ports inside the species, as with a normal component, but also to ports inside the ecosystem containing the species.

They can NOT point to other species of the ecosystem (for inter-species connection, one must exploit the use abstraction detailed [[SpeADL Full Reference#The Use Abstraction|below]]).

h3. Example

<pre>

namespace simple.ecos {	

	ecosystem MyFirstEco {

		species S(name: String) {

			provides p1: AJavaInterface = c.portName

			provides p2: AJavaInterface

			requires p3: AnotherJavaInterface

			part c: MyBeautifulComponent {

				bind anotherPortName to p3

			}

		}

	}

}

</pre>

h2. Ecosystem and Species Implementation

Implementing an ecosystem is similar to implementing a component.

The only difference is with the species: there are methods to implement to provide for an implementation of the species and there are methods that can be used to create instances of species from within the implementation of the ecosystem.

The idea is that the only way of instantiating a species is from within an ecosystem: if one needs to do it from the exterior of the component, some ports must be defined whose implementation does the actual species instantiation.

h3. Special Method to Implement

Each species *S* must be implemented by overriding a method called *S make_S()* where S is also the name of an static inner class of the ecosystem generated abstract class.

It means that in order to implement the method *make_S()*, it is necessary to extends the class S in any way desired.

The implementation of the species can either directly subclass S in an anonymous way in the *make_S()* method, be defined in its own file, or, as it is often done, defined as an inner class of the ecosystem.

This last possibility can be useful to access to some Java class member of the ecosystem class for example.

h3. Special Methods to Exploit

Each species *S* can be instantiated as many times as desired by calling the method *S.Component newS()* which will also take arguments for the parameters declared in the species.

This method is accessible only from within the ecosystem implementation, it can be done for example in the implementation of one of its provided ports or in its *start()* method.

From the implementation of the species, the required and provided ports as well as the parts can be accessed through the same methods as normal component class implementations: *requires()*, *provides()* and *parts()*.

On top of this, the required and provided ports, and the parts, of the ecosystem containing the species can be accessed respectively with *eco_requires()*, *eco_provides()* and *eco_parts*.

h3. Example

<pre>

package testpackage;

import my.interfaces.AJavaInterface;

import simple.ecos.MyFirstEco;

import simple.stuffs.MyBeautifulComponent;

public class MyFirstEco1 extends MyFirstEco {

	@Override

	protected S make_S(final String name) {

		return new S() {

			@Override

			protected AJavaInterface make_p2() {

				return new AJavaInterface() {

					@Override

					public String aMethod(Integer param1) {

						return name+"/"+param1;

					}

				};

			}

			@Override

			protected MyBeautifulComponent make_c() {

				return new MyComponentImpl();

			}

		};

	}

}

</pre>

Of course, one can extract the implementation of the species, either as an inner class of the ecosystem implementation, or even put it in another Java file if desired.

<pre>

public class MyFirstEco1 extends MyFirstEco {

	@Override

	protected S make_S(String name) {

		return new SImpl(name);

	}

	private final class SImpl extends S {

		private final String name;

		public SImpl(String name) {

			this.name = name;

		}

		@Override

		protected AJavaInterface make_p2() {

			return new AJavaInterface() {

				@Override

				public String aMethod(Integer param1) {

					return name+""+param1;

				}

			};

		}

		@Override

		protected MyBeautifulComponent make_c() {

			return new MyComponentImpl();

		}

	}

}

</pre>

h2. The Use Abstraction

As we said previously, species can only be defined inside ecosystems.

Such a relation can be exploited either:

* At the SpeADL level with the bindings and delegation from the species to the ecosystem as described [[SpeADL Full Reference#Ecosystem and Species Definition|above]].

* At a higher-level using advanced interconnection mechanisms between ecosystem and their species.

We focus on the second point in this section with the *use* abstraction.

It is a construct that enables to:

* Build tailored ecosystem-species relations.

* Build tailored inter-species relations mediated by the ecosystem.

h3. Keywords

Inside a species, a special type of part (and for the rest it behave exactly as a part) can be declared using the keyword *use* followed by a name without capital letter.

It follows the syntax _use name: partName.SpeciesName_ where:

* _partName_ is the name of a part in the ecosystem containing the current species and whose type is an ecosystem.

* _SpeciesName_ is the name of a species declared in the ecosystem of _partName_.

* And optionally a list of arguments for the species parameters: one can refer to the parameters of the containing species only.

h3. Details

The important point about the *use* abstraction is that it relies on the definition of ecosystem and species: it is a way to recursively exploit an ecosystem and its species in another ecosystem and its species.

The contained ecosystem and its parts are instantiated with the containing ecosystem, and its species instantiated with the species that use them.

h3. Example

<pre>

namespace simple.ecos {	

	ecosystem MySecondEco {

		part e: MyFirstEco

		species S(name: String) {

			part c: MySimpleComponent

			use s: e.S(name) {

				bind p3 to c.p1

			}

		}

	}

}

</pre>

h2. Lifecycle of Species Initialisation at Instantiation

For a species *S*, when *newS(params...)* is called from the ecosystem implementation, this is what happens:

# The species implementation is instantiated (see below).

# The species is instantiated from the implementation (see below).

# The instance is started (see below).

h3. Species Implementation Instantiation

# The implementation of S is instantiated with the *make_S(params...)* method.

# For each part *useX* of *S* in the order of declaration:

## The species implementation is instantiated from the ecosystem part following the current procedure.

h3. Species Instantiation

# For each part *partX* or use *useX* in the order of declaration

** If it is a part:

### The implementation is instantiated with the *make_partX()* method.

### The component is instantiated from the implementation following the [[SpeADL Minus Reference#Component Instantiation 2|Component Instantiation procedure]].

** If it is a use:

### The use's species is instantiated from the implementation following the current procedure.

# For each provided port *portX* in the order of declaration:

## The interface implementation is instantiated with the *make_portX()* method.

h3. Species Instance Start

# For each part *partX* or use *useX* in the order of declaration:

** If it is a part:

### The part is started following the [[SpeADL Minus Reference#Component Instance Start|Component Instantiation procedure]].

** If it is a use:

### The use is instantiated following the current procedure.

# The implementation *start()* method is called.