Difference between revisions of "Extending the Static Checker (How to extend Rodin Tutorial)"

From Event-B
Jump to navigationJump to search
imported>Pascal
imported>Tommy
 
(23 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{Navigation|Previous= [[Extending_the_Static_Checker(How_to_extend_Rodin_Tutorial)]] | Up= [[Plug-in_Tutorial|How to extend Rodin Tutorial (Index)]] | Next= }}
+
{{Navigation|Previous= [[Providing_help_for_your_plug-in_(How_to_extend_Rodin_Tutorial) | Providing help]] | Up= [[Plug-in_Tutorial|How to extend Rodin Tutorial (Index)]] | Next= [[Extending_the_Proof_Obligation_Generator(How_to_extend_Rodin_Tutorial) | Generating the proof obligations]]}}
  
 
=== In this part ===
 
=== In this part ===
Line 5: Line 5:
 
We will see how to add rules to statically check the machines after our extension. The Static Checker (SC) is one dedicated part of the Proof Obligation (PO) generation process. Indeed, the POs are generated from the statically checked version of the model taken into account. Hence, we have to ensure before creating POs, that the model is correctly expressed (i.e. POs are generated for a model which "''could'' have some sense"). This means that we have to verify some additional properties on the newly added elements. <br>
 
We will see how to add rules to statically check the machines after our extension. The Static Checker (SC) is one dedicated part of the Proof Obligation (PO) generation process. Indeed, the POs are generated from the statically checked version of the model taken into account. Hence, we have to ensure before creating POs, that the model is correctly expressed (i.e. POs are generated for a model which "''could'' have some sense"). This means that we have to verify some additional properties on the newly added elements. <br>
 
The question addressed here is: " '''Under which conditions (about the model well-formedness) the PO generation means something?''' ".<br>
 
The question addressed here is: " '''Under which conditions (about the model well-formedness) the PO generation means something?''' ".<br>
 +
Additional information is available [http://wiki.event-b.org/index.php/Extending_the_Static_Checker here].
  
 
=== Principles ===
 
=== Principles ===
Line 11: Line 12:
 
There are two types of modules: <tt>processorType</tt> and <tt>filterType</tt>. We will detail the way to define such modules later.<br>
 
There are two types of modules: <tt>processorType</tt> and <tt>filterType</tt>. We will detail the way to define such modules later.<br>
 
2. Then, one has to '''set up a configuration''' involving these modules and giving them a hierarchy. In fact, verifying the correctness conditions about added elements can be separated in several processor and filter modules; the configuration is then used to organise them.<br>
 
2. Then, one has to '''set up a configuration''' involving these modules and giving them a hierarchy. In fact, verifying the correctness conditions about added elements can be separated in several processor and filter modules; the configuration is then used to organise them.<br>
3. Finally, it is needed to '''add this configuration''' to the default one, so our checkings can be performed.<br>
+
3. Finally, it is needed to add a reference to (e.g. include) this created configuration to the default one (the SC and POG configuration used by rodin), so our static checkings can be performed.<br>
  
=== Step 1 : Extending the database to introduce the static checked version of the element ''Bound'' (a.k.a. SCBound) ===
+
=== Step 1: Extending the database to introduce the static checked version of the element ''Bound'' (a.k.a. SCBound) ===
  
 
The aim of static checking is to produce a static checked version of the model upon consideration. Hence, every element ("unchecked") shall have its statically checked counterpart. We will then add the counterpart of the element <tt>Bound</tt>, following the same steps as when we added our element <tt>Bound</tt> in the database (See step 4 [[Extend_Rodin_database_(How_to_extend_Rodin_Tutorial)|here]]).
 
The aim of static checking is to produce a static checked version of the model upon consideration. Hence, every element ("unchecked") shall have its statically checked counterpart. We will then add the counterpart of the element <tt>Bound</tt>, following the same steps as when we added our element <tt>Bound</tt> in the database (See step 4 [[Extend_Rodin_database_(How_to_extend_Rodin_Tutorial)|here]]).
Line 22: Line 23:
 
- a class for this element that extends <tt>SCExpressionElement</tt> and implements a freshly created interface <tt>ISCBound</tt> defined as follows:
 
- a class for this element that extends <tt>SCExpressionElement</tt> and implements a freshly created interface <tt>ISCBound</tt> defined as follows:
  
  public interface ISCBound extends ISCExpressionElement{
+
  public interface ISCBound extends ISCExpressionElement, ITraceableElement {
 
 
 
 
 
  IInternalElementType<ISCBound> ELEMENT_TYPE =
 
  IInternalElementType<ISCBound> ELEMENT_TYPE =
Line 28: Line 29:
 
  }
 
  }
  
=== Step2 : Adding modules===
+
=== Step 2: Adding modules===
  
In our case of probabilistic reasoning, the following '''well-formedness conditions should be held''' for a model ''containing probabilistic events'' :
+
==== Generalities ====
# The variant V (declared as usual) is either of the type integer or some set.
+
In our case of probabilistic reasoning, the following '''well-formedness conditions should be held''' for a model ''containing probabilistic events'':
# There is exactly one bound for a model where the probabilistic converge is proved. The bound element B must be of the same type as the declared variant.
+
# The variant V (declared as usual) shall be either of type integer or some set.
# Every probabilistic event must be refined by a probabilistic event.
+
# There is exactly one bound for a model where the probabilistic convergence is proved. The Bound element B shall be of the same type as the declared variant.
 +
# Every probabilistic event shall be refined by a probabilistic event.
 
# The result of merging a probabilistic event and a convergent event is a probabilistic event.
 
# The result of merging a probabilistic event and a convergent event is a probabilistic event.
  
We can face two types of situations during the static checking :
+
We can face two types of situations during the static checking:
# we encounter a problem which doesn't affect the PO generation : this leads to a '''warning''' (corrected by a default assumption or not).
+
# We encounter a problem which doesn't affect the PO generation: it leads to a '''warning''' (fixed by a default assumption or not).
# we encounter a problem which affects the PO generation : this leads to an '''error'''. (the element (added with our extension) under consideration is not added in the statically checked model).
+
# We encounter a problem which affects the PO generation: it leads to an '''error''' (The element, added with our extension and under consideration, is not added in the statically checked model).
  
From the two types of modules, we will first use a <tt>processorModule</tt>. Processor modules literally process the elements, storing them once validated in the static checked file.  
+
We have previously said that there is two types of modules. We first define a <tt>processorModule</tt>. Processor modules literally process the elements, storing them once validated in the statically checked file.  
Whereas <tt>filterModule</tt>s performs only some verifications (i.e. a <tt>filtermodule</tt> can not do anything with the statically checked file). Furthermore, the filters are called (in group) from processors, and as soon as one filter rejects one element (i.e. "does not accept the element"), the other filters will not be evaluated for this element.  
+
In parallel, a <tt>filterModule</tt>s performs only some verifications (i.e. a <tt>filtermodule</tt> cannot do anything with the statically checked file). Furthermore, the filters are called (in group) from processors, and as soon as one filter rejects one element (i.e. "does not accept the element"), the other filters will not be evaluated for this element.  
  
In a <tt>processorModule</tt>, if the static check fails for the considered element, the module '''must not add such element''' to the statically checked file that it holds, and which is used for proof obligation generation. Processors are also responsible of running sub-processors, and filters, as well as adding states to the repository if required.<br>
+
In a <tt>processorModule</tt>, if the static check fails for the considered element, the module '''must not add such element''' to the statically checked file that it holds, and which is used for PO generation. Processors are also responsible of running sub-processors, and filters, as well as adding states to the repository if required.<br>
The developer is responsible of its module configuration lifecycle. He must be aware, at any time, of his module's hierachy, and call submodules explicitely when this is meaningful. Furthermore, a system of state sharing (via a state repository) is available so that a processor can provide informations about its checking results to its submodules. See <tt>org.eventb.core.sc.state.ISCStateRepository</tt> and <tt>org.eventb.core.sc.state.ISCState</tt>. Remember that it is only allowed to share informations within a module/sub-module hierarchy and that a policy should be established so that concurrent access to those states is taken into account, and that informations stored in the state repository are still coherent through sub-processors and filters computations.<br>
+
The developer is responsible of its module configuration lifecycle. He has to be aware, at any time, of his module's hierarchy, and has to call sub-modules explicitly when meaningful. Furthermore, a system of state sharing (via a state repository) is available so that a processor can provide informations about its checking results to its sub-modules. See <tt>org.eventb.core.sc.state.ISCStateRepository</tt> and <tt>org.eventb.core.sc.state.ISCState</tt>. Remember that it is only allowed to share informations within a module/sub-module hierarchy and that a policy should be established so that concurrent access to these states is taken into account, and that informations stored in the state repository are still coherent through sub-processors and filters computations.<br>
  
Three methods can be used (e.g. overriden) in a <tt>processorModule</tt>:
+
Three methods can be used (e.g. overridden) in a <tt>processorModule</tt>:
<tt>void initModule(IRodinElement element, ISCStateRepository repository, IProgressMonitor monitor) throws CoreException</tt>  
+
* <tt>void initModule(IRodinElement element, ISCStateRepository repository, IProgressMonitor monitor) throws CoreException</tt>, which by default does nothing, but should be used in order to initialise the state (e.g. information) sharing.
which by default does nothing, but should be used in order to initialise the state (e.g. information) sharing.<br>
+
* <tt>void process(IRodinElement element, IInternalElement target, ISCStateRepository repository, IProgressMonitor monitor) throws CoreException</tt>, which MUST be implemented to perform static checking.
<tt>void process(IRodinElement element, IInternalElement target, ISCStateRepository repository, IProgressMonitor monitor) throws CoreException</tt>
+
* <tt>void endModule(IRodinElement element, ISCStateRepository repository, IProgressMonitor monitor) throws CoreException</tt>, which by default does nothing, but should be used if <tt>initModule()</tt> was used, to release the states locally created.<br>
which ''MUST'' be implemented to perform static checking.<br>
 
<tt>void endModule(IRodinElement element, ISCStateRepository repository, IProgressMonitor monitor) throws CoreException</tt>
 
which by default does nothing, but should be used if <tt>initModule()</tt> was used, to release the state informations locally created.<br>
 
  
The processor, that we will create, will perform checkings and eventually, add the statically checked version of the bound to the statically checked machine. As we don't really need to share informations to our submodules, only the <tt>process()</tt> method will be overriden.
+
==== Adding a processor module ====
 +
The processor that we will create will perform checks, and eventually add the statically checked version of the Bound element to the statically checked machine. As we don't really need to share information to our sub-modules, only the <tt>process()</tt> method will be overridden.
  
 
For the extension point <tt>org.eventb.core.scModuleTypes</tt> create an extension <tt>processorType</tt>.<br>
 
For the extension point <tt>org.eventb.core.scModuleTypes</tt> create an extension <tt>processorType</tt>.<br>
1. enter a unique ID (like here <tt>machineBoundModule</tt>),<br>
+
1. Enter a unique ID (like here <tt>machineBoundModule</tt>).<br>
2. enter a human readable name such as "Machine SC Bound Module" as we will start to check bound elements,<br>
+
2. Enter a human readable name such as "Machine SC Bound Module" as we will start to check bound elements.<br>
3. enter the parent id of the module we want to extend. Here as we want to make checkings on bounds, variants and events, we will take <tt>org.eventb.core.machineModule</tt> as parent,<br>
+
3. Enter the parent ID of the module we want to extend. Here as we want to make checks on bounds, variants and events, we will take <tt>org.eventb.core.machineModule</tt> as parent.<br>
4. create the module class that <tt>extends SCProcessorModule</tt> (we called it "MachineBoundModule" and we used the "new class wizard").
+
4. Create the module class that <tt>extends SCProcessorModule</tt> (we called it "MachineBoundModule" and we used the "new class wizard").
  
The module (e.g. the class we created) needs to be implemented.<br>
+
The module class we created has to be implemented.<br>
Two methods inherited from the interface ISCProcessorModule need to be defined (e.g. @Override) :
+
Two methods inherited from the interface <tt>ISCProcessorModule</tt> have to be defined (e.g. <tt>@Override</tt>):
  
''A . public IModuleType<?> getModuleType()''
+
''A . <tt>public IModuleType<?> getModuleType()</tt>''
  
This method shall return the type of our module, built from its extension's ID. To do this we use the static method in <tt>org.eventb.core.sc.SCCore.getModuleType()</tt> with our module extension complete identifier : <tt>QualProbPlugin.PLUGIN_ID + ".machineBoundModule"</tt>.<br>
+
This method shall return the type of our module, built from its extension's ID. In order to do that, we use the static method in <tt>org.eventb.core.sc.SCCore.getModuleType()</tt> with the complete identifier of our module extension: <tt>QualProbPlugin.PLUGIN_ID + ".machineBoundModule"</tt>.<br>
Thus, let's use the constant below in our code :
+
Thus, let's use the constant below in our code:
  
 
  public static final IModuleType<MachineBoundModule> MODULE_TYPE = SCCore.getModuleType(QualProbPlugin.PLUGIN_ID + ".machineBoundModule");
 
  public static final IModuleType<MachineBoundModule> MODULE_TYPE = SCCore.getModuleType(QualProbPlugin.PLUGIN_ID + ".machineBoundModule");
  
So we can write :
+
So we can write:
  
 
  @Override
 
  @Override
Line 79: Line 79:
 
  }
 
  }
  
''B . public void process(IRodinElement element, IInternalElement target, ISCStateRepository repository, IProgressMonitor monitor) throws CoreException''
+
''B . <tt>public void process(IRodinElement element, IInternalElement target, ISCStateRepository repository, IProgressMonitor monitor) throws CoreException</tt>''
  
This method is the place where checkings are done. Thus it's where we will code all the conditions to check and finally produce a statically checked bound element, if all those conditions are respected.
+
This method is the place where checks are performed. Thus, it is where we will code all the conditions to check and finally produce a statically checked Bound element if all the conditions are respected.
Accorded to the checking implementations which are "huge" and pure java, it is not relevant for this part of the tutorial to detail the full code. We will rather explain which are the main operations performed by the <tt>process</tt> method and give some hints about how to use the Rodin API to retreive the informations needed in our checkings. Full implementation is let to the reader as an exercise.
+
The implementation is "huge" and pure Java, and it is not relevant in this tutorial to detail the full code. We will rather explain which are the main operations performed by the <tt>process</tt> method and give some hints about how to use the Rodin API to retrieve the information required in our checks. Full implementation is let to the reader as an exercise.
  
 
Here are some explanations about the <tt>process()</tt> method arguments:
 
Here are some explanations about the <tt>process()</tt> method arguments:
  
The <tt>element</tt> passed as an argument here, is the element passed by the parent of this module. It can be useful in case of systematic element checking, to retrieve the elements to check in a parent processor module, and then, treat each element one by one, calling sub-processor modules.<br>
+
The <tt>element</tt> passed as argument here is the element propagated by the parent of this module. It may be useful in case of systematic element checking, to retrieve the elements to check in a parent processor module, and then manage each element one by one, calling sub-processor modules.<br>
The <tt>IInternalElement target</tt> is (e.g. should be) the statically checked file where our elements, after sucessful well-formedness verification, should be stored. This file will be used as an input for the proof obligation generation.<br>
+
The <tt>IInternalElement</tt> target is the statically checked file where our elements, after successful well-formedness verification, will be stored. This file will be used as an input for the PO generation.<br>
The parameter <tt>ISCStateRepository repository</tt> is the global repository used by the module to get shared informations. (//FIXME complete the static checker page, to add infos about states and link it here).<br>
+
The parameter <tt>ISCStateRepository</tt> repository is the global repository used by the module to get shared information. (//FIXME complete the static checker page, to add infos about states and link it here).<br>
Finally, <tt>IProgressMonitor monitor</tt> is the progress monitor used while performing the static checking, subtasks can be created for it, so the user interface reflects the checkings which are done.
+
Finally, <tt>IProgressMonitor</tt> monitor is the progress monitor used while performing the static checks. Sub-tasks can be created for it.
  
In our case, we must refine the well-formedness conditions into a verification algorithm. We choosed to retreive the bound and variant values from the machine root directly using the following code in the <tt>process</tt> method :
+
In our case, we have to refine the well-formedness conditions into a verification algorithm. We choose to retrieve the bound and variant values from the machine root directly using the following code in the <tt>process</tt> method:
  
 
  final IRodinFile machineFile = (IRodinFile) element;
 
  final IRodinFile machineFile = (IRodinFile) element;
Line 98: Line 98:
 
  final IVariant[] variants = machineRoot.getVariants();  
 
  final IVariant[] variants = machineRoot.getVariants();  
  
Warnings and errors will be created using the method <tt>createProblemMarker()</tt>(see <tt>org.eventb.core.sc.SCModule</tt>).
+
Warnings and errors will be created using the method <tt>createProblemMarker</tt> (see <tt>org.eventb.core.sc.SCModule</tt>).
  
Exercise 1 : Implement the proposed algorithm (among a lot of possible other):
+
==== Exercise 1 - Implement the proposed algorithm (among others) ====
  
  if the machine does not contain a probabilistic event, but there is a bound
+
  If the machine does not contain a probabilistic event, but there is a bound,
  then we add a warning informing that the bound is ignored
+
  then we add a warning informing that the bound is ignored.
 
   
 
   
  if the machine contains at least a propabilistic event (i.e. say "the model is probabilistic"), but there are more than one bound
+
  If the machine contains at least a probabilistic event (i.e. "the model is probabilistic"), but there are more than one bound,
  then we create an error telling that there are too many bounds, nothing is created an we return immediately
+
  then we create an error telling that there are too many bounds, nothing is created an we return immediately.
 
   
 
   
  // we now know that there is at maximum one bound
+
  // We are now sure that there a single bound
  if the model is probabilistic  
+
  If the model is probabilistic  
 
      
 
      
     if the variant is not a set or a constant, we create an error and return;
+
     If the variant is not a set or a constant, we create an error and return.
       NB: we can use the following code :
+
       The following code may serve as a basis:
 
   
 
   
 
       private boolean assertIsASetOrConstant(IExpressionElement element)
 
       private boolean assertIsASetOrConstant(IExpressionElement element)
 
  throws RodinDBException {
 
  throws RodinDBException {
 
               final String formula = element.getExpressionString();
 
               final String formula = element.getExpressionString();
               final IParseResult result = factory.parseExpression(formula, LanguageVersion.V2, element);
+
               final IParseResult result = factory.parseExpression(formula, element);
 
               final Expression boundExpression = result.getParsedExpression();
 
               final Expression boundExpression = result.getParsedExpression();
 
               return isASetOrConstant(boundExpression.getType());
 
               return isASetOrConstant(boundExpression.getType());
Line 134: Line 134:
 
  }
 
  }
 
      
 
      
     if there is no bound, we create an error, and return;
+
     If there is no bound, we create an error, and return.
 
   
 
   
     if the bound is not a set or a constant, we create an error, and return;
+
     If the bound is not a set or a constant, we create an error, and return.
 
   
 
   
     if the bound is not of the same type as the variant, we create an error and return;
+
     If the bound is not of the same type as the variant, we create an error and return.
       NB: one could check it this way :  
+
       One may check it as follows:  
 
                         if (!getType(bound).equals(getType(variant))) {
 
                         if (!getType(bound).equals(getType(variant))) {
 
  createProblemMarker(bound,
 
  createProblemMarker(bound,
Line 147: Line 147:
 
  }
 
  }
 
     [...]
 
     [...]
  // after all checkings... we add the bound to the statically checked file :
+
 
 +
  // After all checks, we add the bound to the statically checked file.
 
  final ISCBound scBound = target.getInternalElement(ISCBound.ELEMENT_TYPE, BOUND_NAME_PREFIX);
 
  final ISCBound scBound = target.getInternalElement(ISCBound.ELEMENT_TYPE, BOUND_NAME_PREFIX);
 
  scBound.create(null, monitor);
 
  scBound.create(null, monitor);
 
  scBound.setExpression(getExpression(bound), null);
 
  scBound.setExpression(getExpression(bound), null);
  
In the processor module, one could use the filters to drop a part of the processings using the invocation : <tt>filterModules(element, repository, monitor)</tt> which will return a boolean telling if the element successfully passed all the filtering criteria or not.
+
In the processor module, one may use the filters to drop a part of the processing with the invocation <tt>filterModules(element, repository, monitor)</tt> which will return a boolean telling if the element has successfully passed all the filtering criteria or not.
One can also process an element using the child processor modules using the invocation:<br>
+
One may also process an element using the child processor modules with the following invocation:<br>
  protected final void processModules(IRodinElement element, IInternalElement target, ISCStateRepository repository, IProgressMonitor monitor) throws CoreException
+
  <tt>protected final void processModules(IRodinElement element, IInternalElement target, ISCStateRepository repository, IProgressMonitor monitor) throws CoreException</tt>
  
 
+
==== Exercise 2 ====
Exercise 2 : We used here a filter <tt>machineBoundFreeIdentsModule</tt>, to check that the expression of the ''Bound'' element parses, and no additional free identifier was introduced.
+
We use here a filter <tt>machineBoundFreeIdentsModule</tt> to check that the expression of the ''Bound'' element parses, and that no additional free identifier was introduced.
Implement such a filter using the fact that the repository holds a type environment which contains all the usable free identifiers. To use this, we must add a ''prereq'' clause to our filter pointing the id <tt>org.eventb.core.machineVariantModule</tt> of the variant module.
+
Implement such a filter using the fact that the repository holds a type environment which contains all the usable free identifiers. To use this, we have to add a ''prereq'' clause to our filter pointing the ID <tt>org.eventb.core.machineVariantModule</tt> of the variant module.
Here is an extract of the filter's <tt>accept()</tt> method :
+
Here is an extract of the filter's <tt>accept()</tt> method:
  
 
  final ITypeEnvironment typeEnv = repository.getTypeEnvironment();
 
  final ITypeEnvironment typeEnv = repository.getTypeEnvironment();
Line 178: Line 179:
 
  return ok;
 
  return ok;
  
=== Step 3 : Set up a static checking configuration ===
+
=== Step 3: Setting up the configuration ===
  
In order to register our checkings, and because those verifications could be separated in several modules, we need to encapsulate them into a configuration.<br>
+
In order to register our checks, and because these verifications may be separated in several modules, we need to encapsulate them into a configuration.<br>
The extension point <tt>org.eventb.core.configurations</tt> allows to doing so.<br>
+
The extension point <tt>org.eventb.core.configurations</tt> allows to do that.<br>
To organise our modules :<br>
+
To organise our modules:<br>
1. Create an extension <tt>configuration</tt> from the above mentioned extension point,
+
1. Create an extension <tt>configuration</tt> from the above mentioned extension point.
:give it an id (for example "qpConfig"),
+
:Give it an ID (for example "qpConfig").
:give it a human readable name (for example, "Qualitative Probabilistic Reasoning Plug-in SC Configuration").
+
:Give it a human readable name (for example, "Qualitative Probabilistic Reasoning Plug-in Configuration").
  
2. add the modules (full id) previously defined to the configuration, in our example, we implemented two modules :<br>
+
2. Add the modules (full id) previously defined to the configuration. In our example, we implemented two modules:<br>
 
- <tt>fr.systerel.rodinextension.sample.machineBoundModule</tt><br>
 
- <tt>fr.systerel.rodinextension.sample.machineBoundModule</tt><br>
 
- <tt>fr.systerel.rodinextension.sample.machineBoundFreeIdentsModule</tt><br>
 
- <tt>fr.systerel.rodinextension.sample.machineBoundFreeIdentsModule</tt><br>
  
That's all for configuration creation. Now, we need to add it to machine file configurations so it can run when our plug-in is installed.
+
That's all for configuration creation. Now, we need to add references to machine file configuration elements (e.g. kind of "include") so it can run when our plug-in is installed.
  
=== Step 4 : Add the configuration so it can run on machine files ===
+
=== Step 4: Adding the configuration ===
  
The best way to add our configuration, is to register a utility class, that will add our configuration to the machine files, when our plug-in is active, and their configuration doesn't contain ours.
+
The best way to add our configuration is to register a utility class that will add our configuration to the machine files when our plug-in is active, and if their configuration doesn't contain ours.
 
To do so, create the following class that implements <tt>org.rodinp.core.IElementChangedListener</tt>:
 
To do so, create the following class that implements <tt>org.rodinp.core.IElementChangedListener</tt>:
  
 
  /**
 
  /**
 
   * Class that updates the configuration of files, to add the static checker
 
   * Class that updates the configuration of files, to add the static checker
   * modules for our qualitative probabilistic reasoning plugin.
+
   * modules for our qualitative probabilistic reasoning plug-in.
 
   */
 
   */
 
  public class ConfSettor implements IElementChangedListener {
 
  public class ConfSettor implements IElementChangedListener {
Line 242: Line 243:
 
  }
 
  }
  
Where the string constant ''QUAL_PROB_CONFIG'' will refer to our configuration in the machine files, and we check that each machine file that we are manipulating contains our configuration.
+
Where the string constant ''QUAL_PROB_CONFIG'' refers to our configuration in the machine files. We check that each manipulated machine file contains our configuration.
Now we need to launch this class at plugin start-up.
+
Now we need to launch this class at plug-in start-up.
  
To do so :<br>
+
To do so:<br>
1. open the activator of our plugin,<br>
+
1. Open the activator of our plug-in.<br>
2. add a method <tt>setProbConfig()</tt> to the <tt>start(BundleContext context)</tt> method of the activator,<br>
+
2. Add a method <tt>setProbConfig()</tt> to the <tt>start(BundleContext context)</tt> method of the activator.<br>
3. implement this method the following :<br>
+
3. Implement this method:<br>
 
         /**
 
         /**
 
  * Registers a file configuration setter for our plugin.
 
  * Registers a file configuration setter for our plugin.
Line 256: Line 257:
 
  }
 
  }
  
 
+
{{Navigation|Previous= [[Providing_help_for_your_plug-in_(How_to_extend_Rodin_Tutorial) | Providing help]] | Up= [[Plug-in_Tutorial|How to extend Rodin Tutorial (Index)]] | Next= [[Extending_the_Proof_Obligation_Generator(How_to_extend_Rodin_Tutorial) | Generating the proof obligations]]}}
{{Navigation|Previous= [[Extending_the_Static_Checker(How_to_extend_Rodin_Tutorial)]] | Up= [[Plug-in_Tutorial|How to extend Rodin Tutorial (Index)]] | Next= }}
 
  
 
[[Category:Developer documentation|*Index]]
 
[[Category:Developer documentation|*Index]]
 
[[Category:Rodin Platform|*Index]]
 
[[Category:Rodin Platform|*Index]]
 
[[Category:Tutorial|*Index]]
 
[[Category:Tutorial|*Index]]

Latest revision as of 13:53, 5 September 2013

In this part

We will see how to add rules to statically check the machines after our extension. The Static Checker (SC) is one dedicated part of the Proof Obligation (PO) generation process. Indeed, the POs are generated from the statically checked version of the model taken into account. Hence, we have to ensure before creating POs, that the model is correctly expressed (i.e. POs are generated for a model which "could have some sense"). This means that we have to verify some additional properties on the newly added elements.
The question addressed here is: " Under which conditions (about the model well-formedness) the PO generation means something? ".
Additional information is available here.

Principles

1. To extend the static checker in order to verify some conditions, one has to define a static checker module using the extension point org.eventb.core.scModuleTypes.
There are two types of modules: processorType and filterType. We will detail the way to define such modules later.
2. Then, one has to set up a configuration involving these modules and giving them a hierarchy. In fact, verifying the correctness conditions about added elements can be separated in several processor and filter modules; the configuration is then used to organise them.
3. Finally, it is needed to add a reference to (e.g. include) this created configuration to the default one (the SC and POG configuration used by rodin), so our static checkings can be performed.

Step 1: Extending the database to introduce the static checked version of the element Bound (a.k.a. SCBound)

The aim of static checking is to produce a static checked version of the model upon consideration. Hence, every element ("unchecked") shall have its statically checked counterpart. We will then add the counterpart of the element Bound, following the same steps as when we added our element Bound in the database (See step 4 here).

To do so, create a new extension internalElementType from org.rodinp.core.internalElementTypes with:
- id: scBound,
- a name such as "Event-B Static Checked Bound Element",
- a class for this element that extends SCExpressionElement and implements a freshly created interface ISCBound defined as follows:

public interface ISCBound extends ISCExpressionElement, ITraceableElement {
	
	IInternalElementType<ISCBound> ELEMENT_TYPE =
		RodinCore.getInternalElementType(QualProbPlugin.PLUGIN_ID + ".scBound");
}

Step 2: Adding modules

Generalities

In our case of probabilistic reasoning, the following well-formedness conditions should be held for a model containing probabilistic events:

  1. The variant V (declared as usual) shall be either of type integer or some set.
  2. There is exactly one bound for a model where the probabilistic convergence is proved. The Bound element B shall be of the same type as the declared variant.
  3. Every probabilistic event shall be refined by a probabilistic event.
  4. The result of merging a probabilistic event and a convergent event is a probabilistic event.

We can face two types of situations during the static checking:

  1. We encounter a problem which doesn't affect the PO generation: it leads to a warning (fixed by a default assumption or not).
  2. We encounter a problem which affects the PO generation: it leads to an error (The element, added with our extension and under consideration, is not added in the statically checked model).

We have previously said that there is two types of modules. We first define a processorModule. Processor modules literally process the elements, storing them once validated in the statically checked file. In parallel, a filterModules performs only some verifications (i.e. a filtermodule cannot do anything with the statically checked file). Furthermore, the filters are called (in group) from processors, and as soon as one filter rejects one element (i.e. "does not accept the element"), the other filters will not be evaluated for this element.

In a processorModule, if the static check fails for the considered element, the module must not add such element to the statically checked file that it holds, and which is used for PO generation. Processors are also responsible of running sub-processors, and filters, as well as adding states to the repository if required.
The developer is responsible of its module configuration lifecycle. He has to be aware, at any time, of his module's hierarchy, and has to call sub-modules explicitly when meaningful. Furthermore, a system of state sharing (via a state repository) is available so that a processor can provide informations about its checking results to its sub-modules. See org.eventb.core.sc.state.ISCStateRepository and org.eventb.core.sc.state.ISCState. Remember that it is only allowed to share informations within a module/sub-module hierarchy and that a policy should be established so that concurrent access to these states is taken into account, and that informations stored in the state repository are still coherent through sub-processors and filters computations.

Three methods can be used (e.g. overridden) in a processorModule:

  • void initModule(IRodinElement element, ISCStateRepository repository, IProgressMonitor monitor) throws CoreException, which by default does nothing, but should be used in order to initialise the state (e.g. information) sharing.
  • void process(IRodinElement element, IInternalElement target, ISCStateRepository repository, IProgressMonitor monitor) throws CoreException, which MUST be implemented to perform static checking.
  • void endModule(IRodinElement element, ISCStateRepository repository, IProgressMonitor monitor) throws CoreException, which by default does nothing, but should be used if initModule() was used, to release the states locally created.

Adding a processor module

The processor that we will create will perform checks, and eventually add the statically checked version of the Bound element to the statically checked machine. As we don't really need to share information to our sub-modules, only the process() method will be overridden.

For the extension point org.eventb.core.scModuleTypes create an extension processorType.
1. Enter a unique ID (like here machineBoundModule).
2. Enter a human readable name such as "Machine SC Bound Module" as we will start to check bound elements.
3. Enter the parent ID of the module we want to extend. Here as we want to make checks on bounds, variants and events, we will take org.eventb.core.machineModule as parent.
4. Create the module class that extends SCProcessorModule (we called it "MachineBoundModule" and we used the "new class wizard").

The module class we created has to be implemented.
Two methods inherited from the interface ISCProcessorModule have to be defined (e.g. @Override):

A . public IModuleType<?> getModuleType()

This method shall return the type of our module, built from its extension's ID. In order to do that, we use the static method in org.eventb.core.sc.SCCore.getModuleType() with the complete identifier of our module extension: QualProbPlugin.PLUGIN_ID + ".machineBoundModule".
Thus, let's use the constant below in our code:

public static final IModuleType<MachineBoundModule> MODULE_TYPE = SCCore.getModuleType(QualProbPlugin.PLUGIN_ID + ".machineBoundModule");

So we can write:

	@Override
	public IModuleType<?> getModuleType() {
		return MODULE_TYPE;
	}

B . public void process(IRodinElement element, IInternalElement target, ISCStateRepository repository, IProgressMonitor monitor) throws CoreException

This method is the place where checks are performed. Thus, it is where we will code all the conditions to check and finally produce a statically checked Bound element if all the conditions are respected. The implementation is "huge" and pure Java, and it is not relevant in this tutorial to detail the full code. We will rather explain which are the main operations performed by the process method and give some hints about how to use the Rodin API to retrieve the information required in our checks. Full implementation is let to the reader as an exercise.

Here are some explanations about the process() method arguments:

The element passed as argument here is the element propagated by the parent of this module. It may be useful in case of systematic element checking, to retrieve the elements to check in a parent processor module, and then manage each element one by one, calling sub-processor modules.
The IInternalElement target is the statically checked file where our elements, after successful well-formedness verification, will be stored. This file will be used as an input for the PO generation.
The parameter ISCStateRepository repository is the global repository used by the module to get shared information. (//FIXME complete the static checker page, to add infos about states and link it here).
Finally, IProgressMonitor monitor is the progress monitor used while performing the static checks. Sub-tasks can be created for it.

In our case, we have to refine the well-formedness conditions into a verification algorithm. We choose to retrieve the bound and variant values from the machine root directly using the following code in the process method:

final IRodinFile machineFile = (IRodinFile) element;
final IMachineRoot machineRoot = (IMachineRoot) machineFile.getRoot();
final IBound[] bounds = machineRoot.getChildrenOfType(IBound.ELEMENT_TYPE);
final IVariant[] variants = machineRoot.getVariants(); 

Warnings and errors will be created using the method createProblemMarker (see org.eventb.core.sc.SCModule).

Exercise 1 - Implement the proposed algorithm (among others)

If the machine does not contain a probabilistic event, but there is a bound,
then we add a warning informing that the bound is ignored.

If the machine contains at least a probabilistic event (i.e. "the model is probabilistic"), but there are more than one bound,
then we create an error telling that there are too many bounds, nothing is created an we return immediately.

// We are now sure that there a single bound
If the model is probabilistic 
    
   If the variant is not a set or a constant, we create an error and return.
      The following code may serve as a basis:

      private boolean assertIsASetOrConstant(IExpressionElement element)
			throws RodinDBException {
              final String formula = element.getExpressionString();
              final IParseResult result = factory.parseExpression(formula, element);
              final Expression boundExpression = result.getParsedExpression();
              return isASetOrConstant(boundExpression.getType());

          with

              	private boolean isASetOrConstant(Type type) {
		if (type.equals(factory.makeIntegerType())) {
			return true;
		}
		final Type baseType = type.getBaseType();
		if (baseType != null) {
			return type.equals(factory.makePowerSetType(baseType));
		}
		return false;
	}
   
   If there is no bound, we create an error, and return.

   If the bound is not a set or a constant, we create an error, and return.

   If the bound is not of the same type as the variant, we create an error and return.
      One may check it as follows: 
                       if (!getType(bound).equals(getType(variant))) {
				createProblemMarker(bound,
						EventBAttributes.EXPRESSION_ATTRIBUTE,
						ProbabilisticGraphProblem.VariantBoundTypeError);
				return;
			}
   [...]
// After all checks, we add the bound to the statically checked file.
final ISCBound scBound = target.getInternalElement(ISCBound.ELEMENT_TYPE, BOUND_NAME_PREFIX);
scBound.create(null, monitor);
scBound.setExpression(getExpression(bound), null);

In the processor module, one may use the filters to drop a part of the processing with the invocation filterModules(element, repository, monitor) which will return a boolean telling if the element has successfully passed all the filtering criteria or not. One may also process an element using the child processor modules with the following invocation:

protected final void processModules(IRodinElement element, IInternalElement target, ISCStateRepository repository, IProgressMonitor monitor) throws CoreException

Exercise 2

We use here a filter machineBoundFreeIdentsModule to check that the expression of the Bound element parses, and that no additional free identifier was introduced. Implement such a filter using the fact that the repository holds a type environment which contains all the usable free identifiers. To use this, we have to add a prereq clause to our filter pointing the ID org.eventb.core.machineVariantModule of the variant module. Here is an extract of the filter's accept() method:

		final ITypeEnvironment typeEnv = repository.getTypeEnvironment();
		final Expression parsedExpression = parseResult.getParsedExpression();

		final FreeIdentifier[] freeIdentifiers = parsedExpression
				.getFreeIdentifiers();

		boolean ok = true;
		for (FreeIdentifier ident : freeIdentifiers) {
			if (!typeEnv.contains(ident.getName()))
				createProblemMarker(bound,
						EventBAttributes.EXPRESSION_ATTRIBUTE,
						ProbabilisticGraphProblem.BoundFreeIdentifierError,
						ident);
				ok = false;
			}
		return ok;

Step 3: Setting up the configuration

In order to register our checks, and because these verifications may be separated in several modules, we need to encapsulate them into a configuration.
The extension point org.eventb.core.configurations allows to do that.
To organise our modules:
1. Create an extension configuration from the above mentioned extension point.

Give it an ID (for example "qpConfig").
Give it a human readable name (for example, "Qualitative Probabilistic Reasoning Plug-in Configuration").

2. Add the modules (full id) previously defined to the configuration. In our example, we implemented two modules:
- fr.systerel.rodinextension.sample.machineBoundModule
- fr.systerel.rodinextension.sample.machineBoundFreeIdentsModule

That's all for configuration creation. Now, we need to add references to machine file configuration elements (e.g. kind of "include") so it can run when our plug-in is installed.

Step 4: Adding the configuration

The best way to add our configuration is to register a utility class that will add our configuration to the machine files when our plug-in is active, and if their configuration doesn't contain ours. To do so, create the following class that implements org.rodinp.core.IElementChangedListener:

/**
 * Class that updates the configuration of files, to add the static checker
 * modules for our qualitative probabilistic reasoning plug-in.
 */
public class ConfSettor implements IElementChangedListener {

	private static final String QUAL_PROB_CONFIG = QualProbPlugin.PLUGIN_ID
			+ ".qpConfig";

	public void elementChanged(ElementChangedEvent event) {

		final IRodinElementDelta d = event.getDelta();
		try {
			processDelta(d);
		} catch (final RodinDBException e) {
			// TODO add exception log
		}
	}

	private void processDelta(final IRodinElementDelta d)
			throws RodinDBException {
		final IRodinElement e = d.getElement();

		final IElementType<? extends IRodinElement> elementType = e
				.getElementType();
		if (elementType.equals(IRodinDB.ELEMENT_TYPE)
				|| elementType.equals(IRodinProject.ELEMENT_TYPE)) {
			for (final IRodinElementDelta de : d.getAffectedChildren()) {
				processDelta(de);
			}
		} else if (elementType.equals(IRodinFile.ELEMENT_TYPE)) {
			final IInternalElement root = ((IRodinFile) e).getRoot();

			if (root.getElementType().equals(IMachineRoot.ELEMENT_TYPE)) {
				final IMachineRoot mch = (IMachineRoot) root;
				final String conf = mch.getConfiguration();
				if (!conf.contains(QUAL_PROB_CONFIG)) {
					mch.setConfiguration(conf + ";" + QUAL_PROB_CONFIG, null);
				}
			}
		}
	}
}

Where the string constant QUAL_PROB_CONFIG refers to our configuration in the machine files. We check that each manipulated machine file contains our configuration. Now we need to launch this class at plug-in start-up.

To do so:
1. Open the activator of our plug-in.
2. Add a method setProbConfig() to the start(BundleContext context) method of the activator.
3. Implement this method:

        /**
	 * Registers a file configuration setter for our plugin.
	 */
	public static void setProbConfig() {
		RodinCore.addElementChangedListener(new ConfSettor());
	}