Make Agents Yourself

Make Agents Yourself » MAY Tutorials »

MAY Best Practices » Historique » Révision 9

Révision 8 (Anonyme, 06/10/2014 13:39) → Révision 9/24 (Anonyme, 06/10/2014 13:39)

h1. SpeADL Best Practices 

 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: 
 * Creation of a SpeADL file (see: [[SpeADL MAY Project SetUp]]). 
 * Description of a component. 
 * Creation of the interfaces needed by the component description. 
 * Creation of the implementation of the component extending the corresponding class. 
 * And so on... 

 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 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 to store data 
 ** 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 
 *** Package *impl* containing the implementations 
 *** Package *datatypes* containing extra classes needed to store data 
 *** Package *exception* containing exceptions needed in the interfaces 
 ** 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>