SpeADL Minus Reference » Historique » Révision 31
Révision 30 (Anonyme, 07/10/2014 15:39) → Révision 31/69 (Anonyme, 07/10/2014 16:17)
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, implemented implement in Java, 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 ab bit of an implementation aspect in the form of a composition of components connected together. together through their ports.
From the SpeADL definition, an abstract Java class (which exactly reflects 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
Namespaces are declared 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 (as it is the case in Java). 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.things {
}
namespace simple.stuffs {
}
</pre>
h2. Imports
As in Java, it is possible to import existing names 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 definition is declared defined with the keyword *component* followed by a name starting with a capital letter and must be unique in its namespace.
The keywords *provides* and *requires* 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 _provides *provides name: Interface_ Interface* or _requires *requires name: Interface_, where _Interface_ is a Java type. Interface*.
The keyword *part* is used to declare a part in the component: a component. 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) and letter), a component class definition name.
It takes the form _part *part name: ComponentName_. ComponentName*.
A binding is used to declare for each required port of a part whas is bound to it to fulfil the requirement.
It is done port, using the keywords *bind* and *to* in the form _bind...1 *bind ...1 to ...2_ ...2* where _...1_ *...1* is the name of the required port of the part and _...2_ *...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 *bind req to name.port_. name.port*.
* A provided or a required port of the current containing component, taking the form _bind *bind req to port_. port*.
A delegation is used to declare for the provided port of a component what other port will provides its implementation.
It is done implementation using the keyword * = * followed by a reference to a port available in the current containing component (as with bindings).
It takes the form _provides *provides name: Interface = name.port_ name.port* or _provides *provides name: Interface = port_. port*.
h3. Details
An interface is understood as a Java interface, i.e., a collection of methods, and must be visible declared in the classpath of the Java project.
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.
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. Component Class 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_ *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.
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 what makes a component fundamentally different from an object.
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 implementation for the port 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()_). (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()_). *requires().port().method()*).
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()_). *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();
}
};
}
}
</pre>
Implementing a component with parts, calling a part's provided port:
<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>
h2. Specialisation
In SpeADL, a basic mechanism exists for specialisation of components.
h3. Keyword
When declaring a component class definition, after the name, the keyword *specializes*, followed by a reference to another component name, can be used.
h3. Details
The rules are as follow:
* A component can specialise only a component without parts (i.e., only a pure definition with provided and required ports).
* A component can override provided ports (while respecting the interface or specialising it) to define delegation.
* A component can add provided ports.
* A component CAN'T add required ports.
Only In terms of implementation, only the specialising component needs to be implemented: be: its implementation will contain all the provided ports of the specialisation hierarchy as well as the parts of the specialising component.
An implementation of a specialising component can be used in place of the implementation of the a specialised component.
h3. Examples
<pre>
namespace simple.stuffs {
component S specializes MySimpleComponent {
provides p2: AnotherJavaInterface
}
}
</pre>
h2. Type Parameters
As in Java, it is possible to exploit type parameters (also called generics) when declaring and referencing components, but also in the interfaces of the ports.
h3. Keywords
Contrary to Java, type parameters are enclosed between *[ * and * ]*.
A type parameter can be declared only in a component definition, just after the name declaration.
It has a unique name, a capital first letter, and can be constrained using the keyword *extends* and the name of a class it must be a subclass of.
A type parameter can be used in the name of a referenced component, in a part or in a specialisation declaration.
It must respect the type parameters declared in the referenced component.
A type parameter can also be used in a port definition, just after the name of the referenced interface.
Again it must respect the type parameters declared in the interface.
h3. Details
The possibilities of expressiveness are equivalent to what can be done in Java.
The implementation can either keep the type parameters abstract as in the definition, or can concretise them as long as it respects the type parameter declaration.
Of course interface and component definition references can be parametrised with existing concrete classes.
h3. Example
<pre>
namespace simple.stuffs {
component ParameterisedComponent1[T extends Number] {
provides p1: java.util.concurrent.Callable[T]
provides p2: java.util.concurrent.Callable[String]
}
component ParameterisedComponent2[T1,T2 extends Number] {
part p1: ParameterisedComponent1[T2] {
}
part p2: ParameterisedComponent1[Integer] {
}
}
}
</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. 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.
h3. Details
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.
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. Lifecycle of Component Initialisation at Instantiation
When *newComponent()* is called on a component, this is what happens:
# For each part *partX* in the order of declaration
## The implementation is instantiated with the *make_partX()* method.
## A component is created from it with a process equivalent to *newComponent()* but without *start()* being called.
# 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.
# The component is started (see below).
When a component is started, this is what happens:
# For each part *partX* in the order of declaration
## The part is started (as currently defined).
# The implementation *start()* method is called.