Extending the Static Checker (How to extend Rodin Tutorial)

{{Navigation|Previous= Extending_the_Static_Checker(How_to_extend_Rodin_Tutorial) | Up= How to extend Rodin Tutorial (Index) | Next= [[Extending_the_Proof_Obligation_Generator(How_to_extend_Rodin_Tutorial) | Generating the proof obligations}}

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 this configuration to the default one, so our checks 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, LanguageVersion.V2, 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 SC 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 it to machine file configurations 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());
	}

<prev: Extending_the_Static_Checker(How_to_extend_Rodin_Tutorial)

^up: How to extend Rodin Tutorial (Index)