MAY Best Practices » Historique » Révision 23
Révision 22 (Anonyme, 15/10/2014 17:40) → Révision 23/24 (Anonyme, 17/10/2014 17:14)
h1. MAY Best Practices
{{>toc}}
h2. Typical Workflow
In the Java project, sources (Java and SpeADL) edited by the developer are in the *src* folder (or equivalent), and the generated Java code is in the *speadl-gen* folder.
The *speadl-gen* folder is not meant to be touched by hand.
Each modification of a SpeADL file is followed by the generation of its equivalent Java class.
A typical workflow for creating a component is as follow:
* [[MAY Project Setup|Creation of a SpeADL file]].
* [[Reference Guides|Description of a component]].
* Description of the interfaces needed by the component description.
* [[Reference Guides|Implementation of the component]] extending the corresponding class.
* And so on...
See [[SpeADL Minus Tutorial]] for a detailed tutorial.
h2. Module View
On top of component declarations, interfaces and component implementation, it is relevant to define sometimes datatypes used in the interface or as type parameters of the components used.
A software component, its declaration, its implementation and classes it relies on form altogether what is called a module.
When creating interfaces or datatypes for one or several components, it is important to ask oneself to which module (i.e., with a given component) these declarations should belong to and why.
h2. Project Organisation
For a simple project, a good organisation of the src directory is as follow:
* Package my.project
** SpeADL file *myproject.speadl* with a single namespace *my.project*.
** Package *interfaces* containing the interfaces declarations
** Package *impl* containing the implementations
** Package *datatypes* containing extra classes needed
** Package *exception* containing exceptions needed in the interfaces
In this case, all the modules are intermixed together.
For a more complex project, a good organisation of the src directory is as follow:
* Package my.project
** Package aComponent
*** SpeADL file *aComponent.speadl*
*** Package *interfaces* containing the interfaces declarations owned by this component
*** Package *impl* containing the implementation of the component
*** Package *datatypes* containing extra classes needed by this component
*** Package *exception* containing exceptions needed in the interfaces owned by this component
** Package anotherComponent
*** ...
In this case each module has its own package.
h2. Exploiting the Eclipse Editor
h3. Errors
When creating a Java file to implement a component, one has to extend the Java class generated from the component declaration.
Errors are shown in the Java editor, and the Quick Fix *Add unimplemented methods* proposed by Eclipse will generate automatically the skeleton for the Java file.
From that:
<pre>
public class MySimpleComponentImpl extends MySimpleComponent {
}
</pre>
We get that:
<pre>
public class MySimpleComponentImpl extends MySimpleComponent {
@Override
protected AnotherJavaInterface make_p1() {
// TODO Auto-generated method stub
return null;
}
}
</pre>
This gives the possibility to very quickly approach the implementation of a component.
h3. Completion
When implementing the *make_XXX()* method of a provided port, one can exploit completion to gain a lot of time.
For example in the following situation (just after using the Quick Fix):
<pre>
class MySimpleComponentImpl extends MySimpleComponent {
@Override
protected AnotherJavaInterface make_p1() {
// TODO Auto-generated method stub
return null;
}
}
</pre>
Remove the _null_ after the return statement and replace it with _new AnotherJavaInterface_, use completion (*Ctrl+Space*) and select *AnotherJavaInterface() Anonymous Inner Type* to generate the anonymous type declaration as well as the skeleton to implement its methods:
<pre>
public class MySimpleComponentImpl extends MySimpleComponent {
@Override
protected AnotherJavaInterface make_p1() {
return new AnotherJavaInterface() {
@Override
public Integer test() {
// TODO Auto-generated method stub
return null;
}
};
}
}
</pre>
h2. Implementing Provided Ports
When implementing provided ports, there is two main ways of doing it:
* Using an anonymous instance of the interface.
* By implementing the interface directly with the component implementation.
Using an anonymous class is as follow:
<pre>
public class MySimpleComponentImpl extends MySimpleComponent {
@Override
protected AnotherJavaInterface make_p1() {
return new AnotherJavaInterface() {
@Override
public Integer test() {
return 10;
}
};
}
}
</pre>
Implementing the interface is as follow:
<pre>
public class MySimpleComponentImpl extends MySimpleComponent implements AnotherJavaInterface {
@Override
public Integer test() {
return 10;
}
@Override
protected AnotherJavaInterface make_p1() {
return this;
}
}
</pre>
h2. Required Ports and Their Importances
Components expose their required functionalities through explicit ports bound when composition is done.
This is very different from objects that must be given directly an object providing a required functionality.
h3. Implicit Dependencies
An error that must be avoided when defining a component is to express a dependency to a functionality by requiring objects to be passed to their implementation constructor or by instantiating other objects in their implementation.
It is better to explicit such dependencies through required ports.
Of course this rule can be bent when the functionality is really internal to the component implementation and when it has nothing to do with the architecture the component is part of.
But it is a good practice to explicit required functionalities like this for facilitating future evolution.
h3. No Shared Objects between Components
A very dangerous case of the previous discussed case is when two components actually share a reference to a same object.
This really means that there is a functionality that must be explicited through the creation of a third component that exposes the functionality through one of its port.