Make Agents Yourself

h1. Java for SpeADL⁻ Reference Guide

{{>toc}}

In the [[SpeADL Minus Reference|SpeADL⁻ reference guide]] we saw how one can define components and composition of components.

We now present how to implement these components in Java.

h2. Terminology

The reader can refer to the [[MAY Terminology]] document to get an overview of the different terms used in SpeADL.

h2. SpeADL⁻

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

h2. Component Implementation

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

For example, for the previous example _simple.stuffs.MyBeautifulComponent_ defined in SpeADL, a Java class _simple.stuffs.MyBeautifulComponent_ is generated (in the *speadl-gen* folder, different than the *src* folder).

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

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 one thing that makes a component fundamentally different from an object.

If a component does not have any provided port nor parts, then the generated class is not abstract and can be directly instantiated.

h3. Special Methods to Implement

Each provided port *p* of interface *I* must be implemented by overriding a method called *I make_p()* which returns an instance of the implementation for the port.

This instance is used for 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.

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*.

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.

Furthermore, optionally, a method *void start()* can be override as explained [[SpeADL_Minus_Reference#Component-Initialisation|below]].

h3. Special Methods to Exploit

The *requires()* method (inherited from the extended generated class) gives access to each of the required ports (e.g., _requires().port()_).

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().port().method()_).

The *provided()* method  (inherited from the extended generated class) gives access to each of the provided ports in the same manner.

It is possible to access to the provided ports of the part from within the implementation of a composite by using the method *parts()* (e.g., _parts().partName().portName().method()_).

h3. Examples

Implementing a component with a provided port:

<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>

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

<pre>

public class MySimpleComponentImpl extends MySimpleComponent implements AnotherJavaInterface {

	@Override

	public Integer test() {

		return 10;

	}

	@Override

	protected AnotherJavaInterface make_p1() {

		return this;

	}

}

</pre>

Exploiting a required port:

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

			}

			@Override

			public String anotherMethod() {

				return "plop";

			}

		};

	}

}

</pre>

Implementing a component with parts, calling a part's provided port:

<pre>

public class CompositeCompImpl extends MyCompositeComponent {

	@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>

h2. Component Instantiation

In order to instantiate a component from Java, 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.

h3. Details

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

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.

h3. Example

<pre>

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

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

</pre>

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.

h3. Details

In order to do some initialisation at the instantiation of a component (during the call to *newComponent()*), one can override the *void start()* method of the extended abstract class.

h3. Example

<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>

h2. Lifecycle of Component Initialisation at Instantiation

When *newComponent()* is called on a component implementation, this is what happens:

# The component is instantiated  (see below).

# The instance is started (see below).

h3. Component Instantiation

# For each part *partX* in the order of declaration

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

## A component is instantiated from the implementation following the current procedure.

# For each provided port *portX* in the order of declaration (starting with the super-component in case of specialisation)

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

h3. Component Instance Start

# For each part *partX* in the order of declaration

## The part is started following the current procedure.

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