Generic Event-B EMF extensions

Persistence

Event-B EMF Models may be persisted in several ways:

1. inside a Rodin file by extending Rodin and the Event-B EMF persistence with new Rodin elements and synchronisers to load and save. (This is how the Event-B EMF core plugin works, except that the Rodin elements for standard Event-B already existed).
2. inside a Rodin file as a String attribute containing XMI, using the SerialisedExtensionSynchroniser. (This is how UML-B diagrams are saved inside Machines)
3. in EMF format as an XMI file.
4. in plain text using the XText framework.

Here we mainly focus on methods 2 and 3. We are also developing method 4. as a text persistence, but this is described elsewhere. We do not intend to use method 1 as we do not need Rodin to understand the model (because we translate into standard Machines and Context for verification).

For method 2, declare your root meta-class to use the SerialisedExtensionSynchroniser using the extension point org.eventb.emf.persistence.synchroniser e.g.

  <extension
        point="org.eventb.emf.persistence.synchroniser">
     <emfPackage
           name="Statemachines Package"
           nsURI="http://soton.ac.uk/models/eventb/statemachines/2014">
        <synchroniser
              emf_class="Statemachine"
              name="Statemachine"
              rodin_id="ac.soton.eventb.emf.core.extension.persistence.serialisedExtension"
              synchroniser_class="ac.soton.eventb.emf.core.extension.persistence.SerialisedExtensionSynchroniser">
        </synchroniser>
     </emfPackage>
  </extension>

For method 3, due to the way the Event-B EMF framework implements references, it is important to save files using certain non-default styles. To achieve this, declare the content type of your file as ac.soton.eventb.emf.core.extension.persistence.contentType using the extension point org.eclipse.core.contenttype.contentTypes e.g.

  <extension
        point="org.eclipse.core.contenttype.contentTypes">
     <file-association
           content-type="ac.soton.eventb.emf.core.extension.persistence.contentType"
           file-extensions="umlb">
     </file-association>
  </extension>

Navigator

This section describes how to extend the Event-B Navigator to support Event-B EMF extensions.

Contributing new EMF element types to the Navigator view

The Event-B EMF extensions framework makes it easy to contribute new types of models to the Event-B navigator. You just need to tell the framework some details about your models (as follows) and it does the rest.

If the EMF element types are contained in a new file type, declare the new file extension using the extension point:

ac.soton.eventb.emf.core.extension.navigator.emfFileExtensions

This tells the extensions plugin to adapt the emf contents of those files to be shown in the Navigator.

To ensure the EMF elements are labeled and imaged correctly in the Navigator, declare the EMF adapter factory to the framework using the extension point:

ac.soton.eventb.emf.core.extension.navigator.adapterFactories

(Note - the adapter factory is generated by the EMF genmodel in the edit plugin).

Refinement

[THIS SECTION NEEDS REVIEW AND UPDATE]

The Rodin platform provides an extension point for contributing behaviour to the 'Refine' action. For Serialised Event-B EMF extensions, an abstract, reflective refinement contributor class is provided to simplify the task of making a refinement.

The class is:

 ac.soton.eventb.emf.core.extension.navigator.refiner$AbstractExtensionRefiner which implements IRefinementParticipant.

The class should be extended by a client plug-in and the client's class should be registered as a Refinement Participant using the relevant Rodin extension point The client class must implement the method getExtensionID() to return the relevant Extension ID string that identifies such extensions. The client class may override populateReferenceMap(Map<EReference,Boolean>) to add the EReference Features that need to be dealt with, defining which ones are back references to the corresponding abstract element (put true in map) and which ones should reference the corresponding element in the copy (put false in map). The client class may also override populateFilterByTypeList(List<EClass>) to add the EClass of any types of element that should not be copied into the refinement.

The generic refiner class works as follows:

• All serialised extensions of the given Extension ID in the Rodin resource are loaded
• Each one is deep cloned using the Ecore copier utility
• The contents of the clone extension are then searched for any elements of the EClasses in the client supplied list to be filtered. Such elements are deleted from the clone.
• The contents of the clone extension are then searched for elements that own one of the client supplied EReferences.
• For each reference, the reference is either set to reference the corresponding source abstract element or copied so that it corresponds to the abstract reference

Generator

[THIS SECTION NEEDS REVIEW AND UPDATE - Note: The generator is now based on a more generic EMF translator: https://github.com/eventB-Soton/EMF_Translator It is adapted to Event-B : https://github.com/eventB-Soton/EventB_Translator_Support There is a documentation plugin in the EMF translator source code that describes the necessary extension points and how to contribute a specific translation.]

A framework to support the implementation of generators is provided. The framework is designed to support the generation of standard Event-B models from higher-level model extensions that are based on the Event-B EMF modelling extensions framework.

The Generator framework provides:

• A toolbar button to initiate the generation
• Generic code to remove previously generated elements
• Generic code to organise the incorporation of newly generated elements
• Utilities to aid the creation of new elements
• An abstract basis for client defined rules
• An extension point for clients to declare generators and generation rules

The client rules return generation descriptors (rather than modifying the target model directly). The framework takes care of updating the model (within the clients Transactional Editing Domain) provided the generation completes successfully. This ensures that the model is not left in an inconsistent state should the generation fail. The generation descriptors allow the client to specify where the new element should be contained and a priority which will be used to influence the placement of the new element within the containment ordering.

To define a particular generator a client should:

• Define an extension of org.eclipse.ui.handlers to enable the generate command when the activePartID is their Editor (see Defining a generator handler)
• Define an extension of ac.soton.eventb.emf.diagrams.generator.rule to make the generator framework aware of your generator and its rule classes.
• Implement your rule classes

Generation Descriptors

Each rule should return a collection of one or more Generation Descriptors. Generation Descriptors have the following fields which are explained in this section.

• EventBElement parent;
• EStructuralFeature feature;
• Object value;
• Integer priority;
• Boolean editable;
• Boolean remove;

The feature of the parent will be changed in the following ways:

If remove is false:

• 1) If the feature is a containment and the value is an element of the correct kind, the value will be added to the containment in a position according to the priority
• 2) If the feature is a reference and the value is an element of the correct kind, the value will be added to the reference in a position according to the priority
• 3) If the feature is an EAttribute and the value is of the correct type, the feature will be set to the value

Priority can be used to control the relative position of the generated elements

• 1 - must come first
• 10 - not important
• ---user entered items---
• 0 must come after user entered items
• -10 must come last

Editable - this affects read-only status of the generated element and whether or not it will be preserved or re-generated in a subsequent generation.

• false - the element is set as read-only (the user cannot change its attributes nor add/remove children), any existing copy of the element will be deleted and re-generated at each re-generation
• true - the element is not read-only and will not be deleted before re-generation. (N.B. It is the responsibility of the client rules to check whether this element already exists and only only generate a new one if it does not)

If remove is true:

• 1) If the feature is a containment and the value is an element of the correct kind, the value will be deleted from the containment
• 2) If the feature is a reference and the value is an element of the correct kind, the value will be removed from the reference
• 3) If the feature is an EAttribute, the feature will be unset

Implementing Rule Classes

Rule classes must implement IRule. It is recommended the rule classes extend ac.soton.eventb.emf.diagrams.generator#AbstractRule which provides some concise constants for the commonly needed containments and defines some default behaviour (always enabled and dependencies ok). Note that the rule will only be attempted for the type of source element defined in the extension point. However, this could be defined as an abstract base class to allow the rule to operate on several types of element.

A rule has 4 methods:

• boolean enabled (final EventBElement sourceElement)
• boolean dependenciesOK(EventBElement sourceElement,List<GenerationDescriptor> generatedElements)
• boolean fireLate()
• List<GenerationDescriptor> fire(EventBElement sourceElement, List<GenerationDescriptor> generatedElements)

The enabled method can be used to restrict when it applies. More than one rule can be defined for the same kind of element allowing the generation to be decomposed in a maintainable way.

TheDependenciesOK method allows the method to be deferred since the success of rules may depend on what has already been generated. The dependenciesOK method is passed the list of GenerationDescriptors created so far.

The fireLate method forces the rule to be fired when all other rules have been fired. This is usually used when the rules behaviour depends on what other rules have done.

The fire method must return a list of GenerationDescriptors describing what should be generated. The Utility class, Make, provides a convenience method to help construct a GenerationDescriptor from the parent element, the containment feature, the new child and the priority indicator and if needed the editable setting.

Priority may be from 10 to -10, where 1 indicates first in the containment and -10 last in the containment. Elements in the containment that are not (currently) being generated are placed between priorities 10 and 0. Bear in mind that the relative position of different diagrams (extensions)is preserved within each priority band. Also the order of source elements within their containment is preserved within each priority band.

1 2 3 4 5 6 7 8 9 10 <other content> 0 -1 -2 -3 -4 -5 -6 -7 -8 -9 -10

For example, a basic type invariant that doesn't depend on other variables might be placed at position 1 whereas a theorem or invariant included purely for proof purposes might be placed at position -10.

A current limitation of the priority scheme is that there are a limited number of priorities. For example, this could be a problem if a rule needs to calculate positions of each element within a collection based on dependencies of the element instance.

In most cases the generated element should be set as read-only (the default). In this case the element will be deleted and re-generated on each invocation of the generator. The should not change any attributes of the element nor add to its children. In some case, however, it is necessary to generate an element whose contents may be modified by the user. To do this set the editable parameter of the Generation Descriptor. In this case the generated element will not be deleted when the generator is next invoked. The rule must take care not to return another Generation Descriptor if the element has already been generated. It should look for a suitable generated element (to use for adding further generated chldren etc.) and only generate a new one if it doesn't exist.

Where a tree structure is entirely generated within one rule firing (e.g. an event with guards and actions) it is more efficient to construct the entire event and return a single Generation Descriptor that adds that event. It is also possible to do this by returning separate Generation Descriptors to add the event and each guard and action individually.

A typical line from a rule class might look like this:

		ret.add(Make.descriptor(machine,invariants,Make.invariant("myInvariantName", "myVar >0","my comment"),10));

where, ret is the list to be returned and machine is the parent element containing the invariants to be added to.