Make Agents Yourself

h1. Java for SpeADL  Reference Guide

In the [[SpeADL Reference|SpeADL reference guide]] we saw how one can define ecosystems, species and compose them together.

We now present how to implement these 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 Reference|SpeADL Reference Guide]] before reading the current document.

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><code class="java">

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

			}

		};

	}

}

</code></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><code class="java">

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

		}

	}

}

</code></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.