Make Agents Yourself

h1. SpeADL Reference

SpeADL is a language to describe component-oriented architectures and implement them in Java.

This page is decomposed in two parts:

# SpeADL⁻ : it concerns the traditional component-oriented abstractions such as components, interfaces, composites, specialisation, provided and required ports, bindings, etc

# SpeADL: it concerns the specific abstractions introduced by SpeADL to help the development of MAS with ecosystems and species.

h2. SpeADL⁻

In SpeADL, a set of abstractions are provided to define traditional component-oriented architectures.

With it, it is possible to define components and compositions of components, called composites, and to implement them in Java while keeping a strong link between definition and implementation by relying on an Eclipse plugin.

A component (and thus a composite components) is made of two elements: a definition using SpeADL and an implementation using Java.

From the SpeADL definition, an abstract Java class is automatically generated and then relied upon through the Java extension mechanism to implement it in a safe manner.

h3. Namespaces

Components and composites are defined inside namespace using the keyword *namespace*.

A namespace plays the exact same role as a package in Java.

In a SpeADL file, there can be many as namespace (as well as nested ones) as wanted.

Hence a namespace does not have to follow the name of the directory it is located in as in Java.

Here is an example of namespace declarations:

<pre>

namespace simple {

  namespace things {

  }

}

namespace simple.stuffs {

}

</pre>

Each namespace declaration can contain any component as desired as we are going to see.

h3. Imports

As in Java, it is possible to import existing types into a file to avoid referring to them with their fully qualified name (i.e., including their package or namespace) using the keyword *import*.

The syntax is similar to Java:

<pre>

import java.util.Collection

import java.util.*

import simple.stuffs.*

</pre>

Notice that namespace of components are also considered, and that there is no semi-colon ";" at the end of the line.

The imports can be automatically handled and reorganised in Eclipse using the *Ctrl-Shift-O* shortcut as in the Java editor.

h3. Components and Ports

A component is made of a definition and an implementation.

The definition gives it a name and a list of ports that are either provided or required by the component.

Each port has a name and an interface.

An interface is understood as a Java interface, i.e., a collection of methods.

A component that provides a port must thus provide an implementation for its interface.

Inversely, a component that requires a port can use in its implementation the methods of the interface of the required port.

A component with required ports must be composed with other components so that there exist an actual implementation of the interface of the required port: this is covered in the next section.

When implementing a component, one only has to take care of implementing the provided port, and can exploit the required ports without assuming anything about their implementation and who provides it.

This is what makes a component fundamentally different from an object.

A component is defined using the following syntax:

<pre>

import my.interfaces.*

namespace simple.stuffs {

  component ComponentName {

    provides portName: AJavaInterface

    requires anotherPortName: AnotherJavaInterface

  }

}

</pre>

A component is defined using the keyword *component*, has a name and can contains as many port declaration as wanted.

A port has a name and an interface.

The keywords *provides* and *requires* respectfully represents ports that are provided and required by the component and are a mandatory keyword when defining a port inside a component.

Obviously, having an interface means that there must exist already an interface defined with the same name.

Such a definition is done in Java as one would normally do, for example, as follow, in Java files:

<pre>

package my.interfaces;

public interface AJavaInterface {

  public String aMethod(Integer param1);

}

</pre>

<pre>

package my.interfaces;

public interface AnotherJavaInterface {

	public Integer test();

}

</pre>

In SpeADL, one can use completion to complete interface names.

Also, the shortcut to organize imports will take interfaces into account.

h3. Implementations

To implement a component, one has to extend the abstract class generated automatically by the Eclipse plugin.

For example, for the previous example of component, a Java class *simple.stuffs.ComponentName* was generated (in the speadl-gen folder, separated from the src folder).

It is not needed to look at the generated code to use it: when extending the class, some abstract methods must be implemented.

It is a good idea to use the errors shown by the Eclipse Java editor and their quick-fixes to quickly generate the skeleton of the implementation itself.

Each provided port *p* of interface *I* must be implemented by overriding a method called *I make_p()* which returns an implementation for the port used during the whole life of the component (i.e., the *make_p()* method is called only once to construct the port when the component is instantiated).

Usually, one returns in this method an anonymous instance of the interface as the following Java file shows:

<pre>

package testpackage;

import my.interfaces.AJavaInterface;

import simple.stuffs.ComponentName;

public class ComponentImpl extends ComponentName {

	@Override

	protected AJavaInterface make_portName() {

		return new AJavaInterface() {

			@Override

			public String aMethod(Integer param1) {

				return "" + param1 + " and " + requires().anotherPortName().test();

			}

		};

	}

}

</pre>

But the same result can be obtained by implementing the port directly by the component implementation as follow:

<pre>

public class ComponentImpl extends ComponentName implements AJavaInterface {

	@Override

	public String aMethod(Integer param1) {

		return "" + param1 + " and " + requires().anotherPortName().test();

	}

	@Override

	protected AJavaInterface make_portName() {

		return this;

	}

}

</pre>

We can see that the class extends simple.stuffs.ComponentName and that it overrides a method named *make_portName()* after the name of the provided port.

Finally, the requires are accessible through the *requires()* method which gives access to each of the required ports (for example *requires().anotherPortName()* here).

A port being an implementation of an interface (and not of an operation), it is then necessary to call the desired method on it (for example *requires().anotherPortName().test()* here).

h3. Composites