Tutorial : Building a DSL using Kermeta

We start from the main Eclipse window.

Figure 2.1.  Eclipse window

Select : "File" > "New">> "Example.. A window appears. You are asked to choose a wizard for project creation. At the bottom of the list, you will find "Kermeta samples" item. Browse it and select "FSM tutorial Demo". The "Finish" button has been enabled. Click on it.

Figure 2.2.  Wizard for selection

Thanks to the wizard creation project, a project named "fr.irisa.triskell.kermeta.samples.fsm.demoAspect" appeared on the left side of Eclipse.

Figure 2.3.  View of the example project

If you directly want to see the results, the solutions are available into File -> New -> Example -> Kermeta Samples -> FSM Solutions.

Now, you have the reference project and you can follow the tutorial.The next chapter presents the metamodel used in this tutorial.

This is the most ergonomic – but longest – way to create an instance of a meta-model. This method is here presented in its main lines:

You should obtain the following plugins (if we not consider the folder dynamic_instance which is not linked with the EMF editor creation) :

Figure 4.4. Plugins Generated with EMF

You can customize this EMF editor following the example given on the section Customize the generated EMF editor . The next section presents how to use this newly created tree view editor.

To be able to use the generated reflexive editor, a new runtime workbench has to be launched through the tool bar menu:

	Parallelism between edit a model or a metamodel
	Creation of an EMF model follows the same principles that the creation of an Ecore model. Note that the model object, which was EPackage in the meta-model creation, becomes Fsm in the EMF model creation.

You can use another editors to create instances models such as graphical or textual editors. The following sections presents rapidly this kind of editors.

The following code sample load a previously created FSM model. Copy and paste it on org.kermeta.fsm.serialisation/src/kermeta/serialisation.kmt or see the serialisation.kmt file on fr.irisa.triskell.kermeta.samples.fsm.serialisation/src/kermeta/serialisation.kmt.

         @mainClass "fsm_package::Main"
         @mainOperation "main"

        package fsm_package;

        require kermeta
         require  "http://www.kermeta.org/fsm"
         
         
        using kermeta::persistence 
           
           
         using kermeta::standard
         class Main
         {
         operation main() : Void is do
        // Input fsm
        var fsm1 : fsm::FSM
        // Create the repository, then the resource
         var repository : EMFRepository init EMFRepository.new
         var resource : EMFResource 
         resource ?= repository.getResource("platform:/resource/org.kermeta.fsm.serialisation/model/Fsm_dyn_sample1.xmi")
         
         resource.load

// Load the fsm (we get the instance)
 fsm1 ?= resource.one
 
// Check that the fsm was correctly loaded
fsm1.ownedState.each { s | stdio.writeln("-> "+s.name) 
 		  s.outgoingTransition.each { ti | stdio.writeln( "outgoing : " + " source " + ti.source.name  + " target " + ti.target.name + " input : " + ti.input +  " output :  " + ti.output)}
 		 s.incomingTransition.each { to | stdio.writeln( "incoming :  " + " source " + to.source.name  + " target " + to.target.name +" input : " + to.input +  " output : " + to.output )}
 		}
end
 }      

	To serialize the class definition, the nsURI of the meta model need to be known.
	This method permits to retrieve the resource where the model is stored or create a new resource if it does not exist.
	The persistence permits to load and save EMF models. The key word using is used to simplify writing code like import in Java.
	resource is collection of instances which are in the root file. The first instance of this resource is retrieve by the method one. Browse through the resource You can use resource.each if you want to browse through the resource. Create new resource for your instance model You can create a nex resource to contain your model with the method repository.createResource(NsURI instance model, NsURI metamodel) repository is an EMFRepository that contain the resource.

Example 5.1.  Load an EMF model with Kermeta

To run this file simply right click on it (Run As -> Run As Kermeta Application). You should obtain the following trace in the Eclipse's console :

Figure 5.7. Fsm_dyn_sample1.xmi content

At this stage, it should be interesting to be able to modify a previously loaded model using Kermeta before saving it. The procedure is very simple: do your manipulation as if your loaded FSM model is a Kermeta model (which is, in effect, the case!), and then, simply call a save method on the handling resource. For this purpose, the following code can be added at the end of the main operation defined in the above section:

var newstate : fsm::State init fsm::State.new
	newstate.name := "s_new" 
	fsm1.ownedState.add(newstate) 
      // save fsm1 
      resource.save()

A new state s_new appears on the file Fsm_dyn_sample1.xmi.

It is also possible to save the modified model in a new file instead of overwriting the initial one by using the saveWithNewURI() method. To this end, just replace the last line of above code (resource.save()) by the following one:

resource.saveWithNewURI("platform:/resource/org.kermeta.fsm.serialisation/model/modified_dyn_sample1.xmi")

Saving a programmatically generated model requires to use a new specific instruction that add the created Fsm root class to the destination resource. The following code chunk creates a simple EMF model with 2 states (named “foo”, and “bar”), and 2 transitions. Saving it then consists in adding the root class (i.e. the model object) stored in the variable fsm2 into the resource instances.

var another_resource : EMFResource
		another_resource ?= repository.createResource(
       "platform:/resource/org.kermeta.fsm.serialisation/model/Fsm_scratch_sample.xmi",
       "platform:/resource/org.kermeta.fsm.serialisation/metamodel/fsm.ecore")
		var fsm2 : fsm::FSM init fsm::FSM.new
		var s0 : fsm::State init fsm::State.new
		var s1 : fsm::State init fsm::State.new
		var t01 : fsm::Transition init fsm::Transition.new
		var t11 : fsm::Transition init fsm::Transition.new
		s0.name := "foo"
		s1.name := "bar"
		t01.source := s0
		t01.target := s1
		t11.source := s1
		t11.target := s1
		fsm2.ownedState.add(s0)
		fsm2.ownedState.add(s1)
		s0.outgoingTransition.add(t01)
		s1.outgoingTransition.add(t11)
		// save the from-scratch model!
		another_resource.add(fsm2)
		another_resource.save()

This program should return the following FSM model (viewed with the reflexive editor):

Figure 5.8. Fsm_scratch_sample view

The following short code sample provides a comprehensive code template (replace the <words>) for model loading. Note here that the term model object is appropriate (better than root class!): loading a model consists in getting the root class, from which, thanks to the containment property (see section, all the contained instances can be accessed.

@mainClass "fsm_package::Main"
@mainOperation "main"
package fsm_package;
require kermeta 
require "< nsURI of the metamodel >" 

using kermeta::persistence
using kermeta::standard
class Main
{
 operation main() : Void is do 
      // Variable for your input EMF model
      var <my_model_object> : <type_of_my_model>
      // Create the repository, then the resource
      var <my_rep> : EMFRepository init EMFRepository.new 
      var <my_resource> : EMFResource 
      <my_resource> ?= repository.getResource(
      "<relative_path_of_my_model_to_load>"),
      <my_resource>.load
     // Load the emf model - get the root class 
      <my_model_object> ?= resource.one
     // You can now browse your model through its attributes/references 
      <my_model_object>.<an_attribute_of_it>.each { o | 
         stdio.writeln("-> "+o.toString) } )
    // Save your model in another file
      <my_resource>.saveWithNewUri("<relative_path_of_a_file_where_to_save_model>")
 end
}

	Depending models on the same EMFRepository
	Several models which have links between them must be saved into the same EMFRepository. Be careful on saving the resources (unlike load which retrieve all the resources).

If your models have no dependancy between them, you can save them into several EMFRepository.

In the following chapters, we will study the sample fr.irisa.triskell.kermeta.samples.fsm.demoAspect.

We want to execute an FSM model. To do that we must call the "run" operation of the "FSM" class. We are going to do that thanks to a KerMeta script. This script will : load an instance of the FSM meta model stored in a file and call the run operation of these instance.

	Tip
	To launch a script, the interpreter must know the entry point of the program. It can "ask" it to the user thanks to an Eclipse window. Another way might be to add the following statements into your kermeta code : @mainClass which stands for the main class, @mainOperation which stands for the main operation of the main class.

In the FSM example ( fr.irisa.triskell.kermeta.samples.fsm.demoAspect) , those scripts are in the "launcher" directory. Look at "minimization.kmt" script. Here the interpreter knows that entry point of the program is the operation "main" in the "Minimization" class.

Figure 7.1.  The launcher folder

Let's have a look at the file named "minimization.kmt". Open it. Look at the code of the main operation. There is no parameter. To run this script with constraint checking, right click on "minimization.kmt" and select "Run As" and "Kermeta Constrained Application". To run this script without constraint checking, right click on "minimization.kmt" and select "Run As" and "Run As Kermeta Application".

Figure 7.2.  Execution of minimization example

The program asks you for a filename. Put in "../models/sample1.fsm" for example. You are lastly asked for a filename which will correspond to the file generated by the program. Put in "../generated.fsm" and see the execution.

Now if you have a look at the three others scripts (checkInvariants, determinization and fsmLauncher) into fr.triskell.kermeta.samples.fsm.demoAspect/launcher you will notice that the main operation of the main class takes one argument. Let's focus on "fsmLauncher.kmt" launcher. The main operation takes one parameter which is the name of the file containing the FSM model. It loads the model, prints it and runs it. If you try the running method above, an exception is raised because the parameterized file does not exist. Indeed we did not specify any filename to the program. So, you cannot use the method above to run those kind of script. That is the reason why we are going to use run configurations. Then right click on "fsmLauncher.kmt" file and select "Run As" and "Run Configurations...". A window appears like the one below. Select the run configuration named "loaderFSM" and look at the different options. Have a special look at the file parameters :

Here, we give the string "../models/sample1.fsm" as a parameter to mainLoadFSM operation to "fsm::Main" class. By clicking on "Run" button, it will start the execution. You can create yourself some new run configurations. Just by left clicking on "Kermeta Application " or "Kermeta Constraint Application" (depending on the constraint checking you want) and select "New" and fill in the required fields.

	Caution
	Eclipse is slash sensible. It only accepts front slash and no backslash. Then /fr.irisa.triskell.kermeta.samples.fsm.demo/launcher/fsmLauncher.kmt is a valid filename whereas \fr.irisa.triskell.kermeta.samples.fsm.demo\launcher\fsmLauncher.kmt is not.

Figure 7.3.  Run configurations

	Tip
	If you want to create a new configuration, just right click on Kermeta Application, or Kermeta Constrained Application and New. Then, fill the fields like above.

Execute "FSM Aspect loader with pre-post check" configuration. When you are asked for a letter , just press enter to send an empty string. Normally, it should provoke the violation of the pre condition. You should obtain the following trace into the console :

State : s1
  Transition : s1-(c/NC)->s2
State : s2
  Transition : s2-(x/y)->s2
Current state : s1
give me a letter : 

stepping...
[kermeta::exceptions::ConstraintViolatedPre:4603]
pre pre2 of operation step of class State violated

Execute "FSM Aspect loader with pre-post check" configuration. When you are asked for a letter , press c and then press enter. Normally, the post condition will be violated because the result will be an empty string. You should obtain the following trace into the console :

State : s1
  Transition : s1-(c/NC)->s2
State : s2
  Transition : s2-(x/y)->s2
Current state : s1
give me a letter : c
c
stepping...
[kermeta::exceptions::ConstraintViolatedPost:5548]
post post3 of operation step of class State violated

This chapter presented the use of pre and post condition on an execution.The next chapter explain how you can simulate an execution of the modelling system thank to behaviour.

Behavior :

1 – initialize current state

2 – loop until the user's input equal to "quit"

print the current state

read a string

process a step

catch exceptions if there are some and exit the program displaying the error.

Here is the code of the operation :

operation run() :  Void raises FSMException is do  
		// reset if there is no current state
		if self.currentState == void then self.currentState := self.initialState end
		self
		from var str : String init "init"
		until str == "quit"
		loop
			stdio.writeln("Current state : " + self.currentState.name)
			str := stdio.read("give me a letter : ")
			if str == "quit" then
				stdio.writeln("")
				stdio.writeln("quitting ...")
			else 
				if str == "print" then
					stdio.writeln("")
				else	
					stdio.writeln(str)			
					stdio.writeln("stepping...")
					do
						var textRes : String
						textRes := self.currentState.step(str)
						if( textRes == void or textRes == "" )
						then
							textRes := "NC"
						end
						
						stdio.writeln("string produced : " + textRes)
					
						rescue (err : ConstraintViolatedPre)
		            		stdio.writeln(err.toString)
		            		stdio.writeln(err.message)
		            		str := "quit"
		            	rescue (err : ConstraintViolatedPost)
	            			stdio.writeln(err.toString)
	            			stdio.writeln(err.message)
	            			str := "quit"
	            		
						rescue(err : NonDeterminism)
							stdio.writeln(err.toString)
							str := "quit"	
						rescue(err : NoTransition)
							stdio.writeln(err.toString)
							str := "quit"
	            	end
				end
			end
		end
	end

In this operation, there are pre and post conditions. These are conditions checked each time the operation is called. If they are evaluated to false an exception is raised. You can choose to check them or not. The following chapter presents how to run configurations.

Behavior :

1 – Select the possible transitions.

2 – If there is none raise a NoTransition exception.

If there is more than one raise a NonDeterminism exception.

3 – If there is only one transition, call its fire operation and return its result.

// Go to the next state
	operation step(c : String) : String raises FSMException
	is do
		// Get the valid transitions
		var validTransitions : Collection<Transition> 
		validTransitions :=	outgoingTransition.select { t | t.input.equals(c) }
		// Check if there is one and only one valid transition
		if validTransitions.empty then raise NoTransition.new end
		if validTransitions.size > 1 then raise NonDeterminism.new end
		
		// Fire the transition
		result := validTransitions.one.fire
	end

Behavior :

1 – change the current state of the FSM

2 – return the produced string

// Fire the transition
	operation fire() : String is do
		// update FSM current state
		source.owningFSM.currentState := target
		result := output
	end

To change an icon you need only to replace the icon from fr.triskell.kermeta.samples.fsm.edit/icons/full/obj16 to another with the same name and the same extension. It is the case on this deployed plugin. The following image presents this plugin, the .gif images have been changed from the initial EMF generation.

Figure 10.2.  Customize icons

Respectively the icons FSM.gif, State.gif and Transition.gif look like this :

Figure 10.3.  FSM icon

Figure 10.4.  State icon

Figure 10.5.  Transition icon

	Note
	Like GMF use EMF icons for the palette you can customize the palette icons by this way.

You will see the change when you will use the generated editor like in the following section.

The following method comes from FSMItemProvider in the package fr.triskell.kermeta.samples.fsm.provider in the project fr.irisa.triskell.kermeta.samples.fsm.model.edit. It permits to disply thr initial state or if it is missing or if the final state is missing.

        /**
	 * This returns the label text for the adapted class.
	 * <!-- begin-user-doc -->
	 * <!-- end-user-doc -->
	 * @generated NOT
	 */
	public String getText(Object object) {
		
		String initialState = " [an initial state is required]";
		if(object instanceof FSM && ((FSM) object).getInitialState()!=null) {
			initialState = " [initial state = " + ((FSM) object).getInitialState().getName() + "]";
		}
		String finalState = " - [at least one final state is required]";
		if(object instanceof FSM && ((FSM) object).getFinalState().size()>0) {
			finalState = "";
		}
		return getString("_UI_FSM_type") + initialState + finalState;
	}
         

.