Make Agents Yourself

h1. SpeADL Minus Reference

{{>toc}}

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

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

A component is made of two elements: a class definition using SpeADL and an implementation using Java.

Optionally, the SpeADL definition can contain an implementation aspect in the form of a composition of components connected together through their ports.

From the SpeADL definition, an abstract Java class (which exactly reflect the content of the definition) is automatically generated and then relied upon through the Java extension mechanism to implement what is left in the component in a safe manner.

h2. Namespaces

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

h3. Keyword

Components is defined inside namespace using the keyword *namespace*.

h3. Details

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.

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

h3. Example

<pre>

namespace simple {

	namespace things {

	}

}

namespace simple.stuffs {

}

</pre>

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

h3. Keyword and Role

As in Java, this is done with the keyword *import*.

h3. Details

The namespace of components are also considered to import component class definitions.

There is no semi-colon ";" at the end of the line.

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

They are always at the top of a SpeADL file.

h3. Example

The syntax is similar to Java:

<pre>

import java.util.Collection

import java.util.*

import simple.stuffs.*

</pre>

h2. Component Class Definition

A software component is made of a class definition and a class implementation: an instance can then be created from the implementation.

A component class definition has provided and required ports, as well as parts which are themselves components.

A part is structurally similar to a class member in Java.

For each required port of a part, there must be a binding declaring what is providing the required port.

h3. Keywords

A component class is defined with the keyword *component* followed by a name starting with a capital letter and must be unique in its namespace.

The keywords *provided* and *required* are used to declare respectively provided and required ports, they are followed by a name (unique in the component and without capital letter) and an interface name.

It takes the form *provided name: Interface* or *required name: Interface*.

The keyword *part* is used to declare a part in the component: a part is structurally similar to a class member in Java.

It is followed by a name for the part (unique in the component and without capital letter), a component class definition name.

It takes the form *part name: ComponentName*.

A binding is used to declare for each required port, using the keywords *bind ...1 to ...2* where *...1* is the name of the required port of the part and *...2* is a reference to a port available in the current containing component.

Such a reference can either be:

* To another part's provided port, taking the form *bind req to name.port*.

* A provided or a required port of the current containing component, taking the form *bind req to port*.

A delegation is used to declare for the provided port of a component what other port will provides its implementation using the keyword = followed by a reference to a port available in the current containing component (as with bindings).

It takes the form "provided name: Interface = name.port* or "provided name: Interface = port*.

h3. Details

An interface is understood as a Java interface, i.e., a collection of methods, and must be declared in the classpath of the Java project.

A component that provides a port will thus provide an implementation for its interface in the component class implementation.

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.

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.

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

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

h3. Example

Component class definitions

<pre>

import my.interfaces.*

namespace simple.stuffs {

	component MySimpleComponent {

		provides p1: AnotherJavaInterface

	}

	component MyBeautifulComponent {

		provides portName: AJavaInterface

		requires anotherPortName: AnotherJavaInterface

	}

	component MyComplexComponent {

		provides p1: AnotherJavaInterface

		provides p2: AnotherJavaInterface = s.p1

		requires p3: AnotherJavaInterface

		part b1: MyBeautifulComponent {

			bind anotherPortName to s.p1 

		}

		part b2: MyBeautifulComponent {

			bind anotherPortName to p1

		}

		part b3: MyBeautifulComponent {

			bind anotherPortName to p3

		}

		part s: MySimpleComponent

	}

}

</pre>

Interface definition in Java:

<pre>

package my.interfaces;

public interface AJavaInterface {

  public String aMethod(Integer param1);

}

</pre>

<pre>

package my.interfaces;

public interface AnotherJavaInterface {

	public Integer test();

}

</pre>

h2. 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.MyBeautifulComponent* 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 files show:

<pre>

package testpackage;

import my.interfaces.AnotherJavaInterface;

import simple.stuffs.MySimpleComponent;

public class MySimpleComponentImpl extends MySimpleComponent {

	@Override

	protected AnotherJavaInterface make_p1() {

		return new AnotherJavaInterface() {

			@Override

			public Integer test() {

				return 10;

			}

		};

	}

}

</pre>

<pre>

package testpackage;

import my.interfaces.AJavaInterface;

import simple.stuffs.MyBeautifulComponent;

public class MyComponentImpl extends MyBeautifulComponent {

	@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 MyComponentImpl extends MyBeautifulComponent 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.MyBeautifulComponent and that it overrides a method named *make_portName()* after the name of the provided port.

Finally, the *requires()* method (inherited from the extended generated class, *MyBeautifulComponent* in the example) gives access to each of the required ports (e.g.,*requires().anotherPortName()* in the example).

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

Of course, nothing else is required than calling it to use it: as we are going to see now, the implementation of a required port is provided by another component composed with the requiring component.

h2. Composites

While defining a component class with a name and ports in SpeADL is only a definition of its external interfaces, a composite of many components connected together is already a partial implementation of this definition.

A composite, on top of provided and required ports, contains parts. A part is structurally similar to a class member in Java.

A part is declared using the *part* keyword and the name of the component class of the part.

Furthermore, if the component class of the part has required ports, then a part will also contain bindings for these required ports using the keyword *bind*.

An example follow:

<pre>

namespace simple.stuffs {

	component MyComplexComponent {

		provides p1: AnotherJavaInterface

		provides p2: AnotherJavaInterface = s.p1

		requires p3: AnotherJavaInterface

		part b1: MyBeautifulComponent {

			bind anotherPortName to s.p1 

		}

		part b2: MyBeautifulComponent {

			bind anotherPortName to p1

		}

		part b3: MyBeautifulComponent {

			bind anotherPortName to p3

		}

		part s: MySimpleComponent

	}

}

</pre>

The keyword *bind* is followed by the name of the required port that is to be bound (completion can be used), then by the keyword *to* then either by:

* The name of another part, a dot, then a provided port of this part (as for *b1* in the example).

* The name of a provided port of the component containing the part (as for *b2* in the example).

* The name of a required port of the component containing the part (as for *b3* in the example).

Furthermore, another type of binding is a delegation of a provided port to another port.

It is declared using the = sign after the provided port declaration (as in *p2* in the example) and can be followed either by a reference to the port of a part, a provided or a required port of the component, as with the normal bindings.

h2. Implementation of Composites

As with the implementation of non-composite component classes, a Java class is generated from the description and it must be extended in order to specify the implementation of the provided ports and of the parts.

Each part *p* of component class *C* has a corresponding abstract method *C make_p()* to override and which must return an instance of an implementation of *C*.

For example:

<pre>

public class ComplexCompImpl extends MyComplexComponent {

	@Override

	protected MySimpleComponent make_s() {

		return new MySimpleComponentImpl();

	}

	@Override

	protected AnotherJavaInterface make_p1() {

		return new AnotherJavaInterface() {

			@Override

			public Integer test() {

				return parts().s().p1().test();

			}

		};

	}

	@Override

	protected MyBeautifulComponent make_b1() {

		return new MyComponentImpl();

	}

	@Override

	protected MyBeautifulComponent make_b2() {

		return new MyComponentImpl();

	}

	@Override

	protected MyBeautifulComponent make_b3() {

		return new MyComponentImpl();

	}

}

</pre>

As we can see, the bindings and other connections inside the components are totally taken care of by the generated code and the implementation only needs what is Java-specific.

It becomes very easy to define new compositions without extra boilerplate code.

Also, it is possible to access to the provided ports of the part from within the implementation of a composite by using the method *parts()* (as in the implementation of the port *p1* in the example).

h2. Instantiation

In order to instantiate a component, one need an instance of an implementation of the component and to call the *newComponent()* method (present in the generated class) to get an instance of the component.

Only component without required port can be manually instantiated: if a component has required ports, it must be composed with other components in a composite component.

For example:

<pre>

MySimpleComponent.Component c = new MySimpleComponentImpl().newComponent();

System.out.println(c.p1().test());

</pre>

As we can see, once we have an instance of a component, we can call the methods of its provided ports.

The same applies for composite components, the instantiation of the part of a composite is done automatically by the generated code.

h2. Component Initialisation

When the implementation of a component is instantiated (before calling *newComponent()*), its constructor is of course called but the component itself is not yet initialised: in particular its provided required ports and parts can't be called at that time.

In order to do some initialisation at the instantiation of a component (during the call to *newComponent()*), one can override the *void start()* method in the implementation as follow:

<pre>

public class MySimpleComponentImpl extends MySimpleComponent {

	@Override

	protected AnotherJavaInterface make_p1() {

		return new AnotherJavaInterface() {

			@Override

			public Integer test() {

				return 10;

			}

		};

	}

	@Override

	protected void start() {

		// do some initialisation using the requires() or the parts(), create a GUI, etc...

	}

}

</pre>