Wednesday, July 05, 2017

Tool supported Papyrus customization

by Draskovits Stefan and Heinzl Michael

Introduction

Papyrus is a model based open source engineering tool. The core feature of Papyrus is to create domain specific applications. Therefore, you can customize every important aspect like: UML profile, model explorer, diagram notation and style, properties views, palette and creation menus and much more.
This customization has a high impact on the usability in real productive environments. Furthermore, this customization mechanism of Papyrus positively influences the pace of work, because only relevant elements are displayed to the user.


Example of a Papyrus instance

Thus the Papyrus environment provides a huge set of customization possibilities. Papyrus has many configuration files, where you can specify exactly the look and feel of the environment. This results in a huge set of files with configuration properties and references, which makes the customization of Papyrus surprisingly complex. The target audience has not the required knowledge and insight in this configuration system. As model based engineering is a rather new field, it is developing constantly.

The approach of Papyrus is a very ambitious one, but too complex for their target audience. This results in a huge overhead to set up a new Papyrus projects. For that reason it is very time costly and more likely to put people off, as there are many possibilities and ways to customize a Papyrus instance. Besides that it requires a lot of time to set up a project, it is also necessary to maintain and update the project. If you want to use a certain feature you have to configure multiple files to achieve the desired result.
Additionally you have to have a certain base knowledge about programming and model driven engineering. As there are so many properties and references in these configuration files it is a lot to process at a time if you are not familiar with the system. In summary the whole process of setting up and maintaining a project is cumbersome and tedious.

This paper deals with exactly with those described problems. Our goal is to develop a meta model with a textual representation to describe a specific set of the customization possibilities and gather them in one place. Furthermore, we develop an automatic tool which can process our meta model and generate all relevant configuration files to build a customized Papyrus instance. Many of those configuration files are an instances of a corresponding meta model. The meta models of the configuration files are used to generate and adapt the files without interfering directly with the textual representation. By using the meta models of the configuration files following advantages emerge:

  • Concise and precise definition of the language concepts Standardized exchange format
  • Checking correctness of models
  • Simple maintenance
  • Extensibility of modelling languages
By using this model oriented approach one can setup a customized Papyrus instance in a few simple steps. Therefore, the setup time decreases significantly. As our textual representation of our meta model is designed for easy use, it is not necessary to read the whole complex Papyrus customization documentation. Furthermore, you only have to specify a certain feature once and it will be added to multiple configuration files. Overall the tool provides a simple but powerful language to describe and generate a Papyrus configuration. 


Meta Model

The meta model which is used as a an input is kept simple on purpose. Users should be able to simply create a model for their needs. The meta model contains the root element CustomPapyrusModel which contains multiple ItemsThe element Item contains one property of type EString which is name. It is used to generate pallet rules, assistant rules and element creation menus, which represents the configuration files for a papyrus instance.

Meta Model


Future work

There are still menus, where it would be nice if they are configured automatically, which is not handle by this project at the moment. Therefore, for future work the tool could be extended with a generator for other features.
  • Properties view
  • Multiple viewpoints Styling (CSS)
  • Extended branding Welcome page
  • UML Profiles 

Tuesday, July 04, 2017

Model Profiling

by Serap Kadam, Andrey Maltsev, Polina Patsuk-Bösch

Introduction

In this work we describe an execution-based model profiling approach by modeling an autonomous-driving vehicle control system in UML, where the main behavior is modeled with statecharts. Code generated from this model provides activity logging information at runtime, which is used to represent the interaction between the components of the system and their behavior. From the outputted logs a sequence diagram (SD) is generated by using a tool called UML Miner. These sequence diagram is then analysed and transformed back to statecharts (SC) by means of metamodeling and model transformation.

Approach

Our approach is based on the unifying conceptual framework for execution-based model profiling. An adapted version of this framework is presented in the figure below.


The framework has two perspectives: the prescriptive perspective on the left-hand side, where design models are used to create a system, and the descriptive perspective on the right-hand side, where observation models are used to describe the actual system behavior at runtime.
In the prescriptive perspective a design model is used to prescribe how a certain system should be built on the modeling level. This design model is created in design language, which resides on the metamodeling level above the design model.
In the descriptive perspective there is an observation language on the metamodeling level. This language refers to the design language in the prescriptive perspective. The observation language captures the operational semantics of the design language, i.e. everything that can change in a running system modeled in this design language.
The observation models conform to the observation language and can be transformed into model profiles for further analysis in diverse tools such as process mining tools, runtime verification tools, monitoring tools.
In our extension of this approach we take sequence diagrams and statecharts as model profiles. We suggest to transform the observation model into a sequence diagram to observe actual interaction of the system components at runtime. The next step is to transform the sequence diagram into one or several statecharts. New statecharts give a different overview of the system and the objects in the system.

Case Study

The main goal of case study is to evaluate to what extent descriptive models such as sequence diagrams and statecharts can be applied to analyze and improve a model-driven engineered system. In particular, we analyze a Raspberry Pi-based car, which software is a fully model-driven engineered system. We enhanced this system with execution-based model profiling capabilities, performed live experiments, collected the runtime information in form of observation models and transformed them into SD and SC.
The example has been modeled using a small subset of UML, which has been named Class/Statecharts (CSC). The modeled state chart of PiCar is shown below.


Technical Realization

The technical realization of the case study has six major steps:
  1. Logging instrumentation of the system under study (SUS) - we implemented a logging component named csvWriter in Python that is used by the SUS at runtime. This component creates a CSV file and adds rows to this file every time the component is called from an operation.
  2. Extension of the code generator - we extended the code generator in such a way, that the name of the required log call can be modeled as tagged values of the package on which the code generation is called. Additionally some mapping or specification for the parameters of the log call has to be introduced.
  3. Transformation of logs into a sequence diagram - we used UML Miner to transform CSV logs into a sequence diagram in XMI format. This XMI file can be imported into Enterprise Architect (http://www.sparxsystems.com/products/ea/), where it is visualized as a sequence diagram. Further we transformed this XMI file into statecharts.
  4. Metamodel extraction from the generated sequence diagrams -  we created a  metamodel for files generated by UML Miner. We decided to construct a XML-schema (XSD) of generated files. To generate XSD we used a tool inst2xsd (Instance to Schema Tool) from XMLBeans Tools library. Then we took the created XSD-files as source for the generation of an Ecore model, that we used for further research.
  5. Transformation of the sequence diagram into a statecharts - we decided to take an approach proposed by Tewfic Ziadi, Loic Helouet and Jean-Marc Jezequel. To realize a sequence diagram into statecharts transformation, we created a target metamodel for state machines in EMF. We used a simplified metamodel of the UML statechart. At this point, generated XMI files from this case study did not contain any additional combined fragments, which are responsible for the composition operators. So the only possible way, we could get basic flat statecharts, was to transform lifelines without any additional conditions, into flat statecharts.
  6. Visualization of the statecharts - we developed a graphical concrete syntax for statecharts with Sirius that allows to display statecharts and results of our research in visual and more human form. We used the graphical concrete syntax to test data and to make high-level analyses of the observation model.
The overview of the technical realization is given below:

 

Observation language

The metamodel of the observation language is derived from the operational semantics of the design language CSC used in the context of this study. Both observation language and design language CSC as well as their relation is depicted in the Figure below. The changes at runtime included updates of the attribute values in the static aspect of the system, i.e. class diagram, and changes of the current state and the current fired transition in the dynamic aspect of the system, i.e. statechart. These elements are tagged with the <<observe>> stereotype.

 

Generated Model Profiles

We derived two types of model profiles from the logs in form of observation models: sequence diagrams and statecharts. We used UML Miner to generate a sequence diagram and the approach described in above to realize the model transformation from sequence diagrams to statecharts.


Conclusion and Future Work

In this work, we transformed an observation model into a sequence diagram and further into statecharts to observe the actual interaction of the system components at runtime and gained new information about the system.
We extended the unifying framework for execution-based model profiling with operation calls. We took a Raspberry Pi-car as a basis for our case study and fulfilled all the requirements for the system under study. We enhanced this system with execution-based model profiling capabilities and realized the prescriptive perspective of the unifying conceptual framework. During the implementation of this case study we extended the used code generator with the possibility of generating log calls in the code. This logging code reflects the operational semantics of the design language. We performed live experiments and collected runtime information in form of observation models. The descriptive perspective was realized by the implementation of transformation of logs into a sequence diagram and transformation of this sequence diagram into statecharts. After the transformation of logs into the sequence diagram we could observe the internal behavior and communication between the systems objects. These results could be used for the high-level analysis, conformance checking and pattern identification.
While the first results seem promising, there are still several open challenges, which were covered in this work. The quality of the information in the generated sequence diagram could be improved with design pattern recognition. After this improvement we hope to fully realize the chosen algorithm for transforming sequence diagrams into statecharts and to get more information for the high-level analysis of the system behavior.

Friday, June 30, 2017

Building IFC metamodel

by Benjamin KIRINDI-HENTSCHEL, Berwan YILDIZ, and Ünzüle KIRINDI-HENTSCHEL

Introduction and problem description

At the beginning of a construction project, the architect's design is based on the wishes of the client as well as on existing laws and regulations. The technical construction and design drawings required for the execution are produced with the aid of CAD systems. The necessary construction work, the bill of quantities and the cost estimations are subsequently determined based on those.
If there are changes in the design, the drawings and calculations concerning, for example, the structural design or the MEP (mechanical, electrical, plumbing) and HVAC (heating, ventilation, air conditioning) - have to be adjusted. In classical building design such adjustments cause a great deal of work and coordination overhead. The stated goal of Building Information Modeling (BIM) is to reduce the above mentioned workload.

The Industry Foundation Classes (IFC) are the implementation specification for the Building Information Modeling standard. They enable data exchange between different software applications of multiple stakeholders in the architecture, engineering and construction (AEC) industries working together throughout the life cycle of a building.

However, since the IFC-Standard is developed by many different domain experts with varying objectives, the standard has grown in complexity over the years, which places restrictions on its extensibility. For these reasons implementations of the standard are time-consuming and not always round-trip-capable in different existing software.

The aim of this project is to build a meta-model for a simplified and more object oriented approach of IFC, which enables extensibility and flexibility. Our model structure should allow an efficient integration of new knowledge and new products in the standard.

Methodology

In this section we will discuss the steps necessary to create a representative meta-model of the IFC standard using the Eclipse Modeling Framework (EMF).
For the first step (building the meta-model) we chose a small subset of types from the Shared Building Elements module for the definition of a closed space (e.g. a room). The chosen subset of the standard is a good representation of the concepts typical of IFC, because the IfcWall type is a complete product model as well as a fundamental part of a building and has most common functionality and properties of a building element.
  • IFC Documentation - Research
    To ensure that the existing technology is utilized to its fullest potential its purpose and usage have to be analyzed and compared to other existing standards.

  • Development of a Class diagram
    The complexity of IFC made the creation of a representative class diagram necessary before starting with the meta-model development. The class diagram provides a graphical representation of entities, abstract classes, their relationships and attributes. The main purpose of the class diagram was to aid in the selection of relevant entities and references for the type IfcWall and to determine which ones are insignificant enough to ignore.

  • Object oriented approach
    The next step is one of the most important steps in the object oriented approach. The fact that IFC is mainly developed by stakeholders such as building and mechanical engineers leaves a software engineer a lot of space for structuring the complex system with a more comprehensive abstraction.

    This means that typical paradigms like classification and inheritance are used to reduce redundancy and duplication of data and attributes, but also for re-usability and extensibility.

    In modeling technology it is common to use design patterns. IFC has utilized multiple design patterns in its specification, some of them producing sub-optimal artefacts. These were analyzed and alternative implementations were designed. One of them is the Type-Object Pattern. This pattern allows an object to be associated with a dynamic object type and, consequently, an object instance to be linked with a particular object type instance. This approach leads to lack of static type safety.

    For this reason the pattern was redesigned using classification. This results in the following structure: The common properties associated with the type IfcWall (residing in the domain type layer) can be made binding by the fact that it is an instance of IfcWallType in the domain meta-type layer. IfcWallType can be seen in the following figure. As the type of both IfcWallStandardCase and IfcWallCollapsibleCase it can enforce the presence of any desired attributes.

Figure 1. on the right: the type-object pattern, on the left: its redesign

  • Development of the meta-model
    Through the process of analysis and simplification five main concepts were selected as basis for the meta-model of type IfcWall:
    – Geometry
    – Material Layer
    – Path Connectivity
    – Local Placement
    – Properties and Quantities

    The next figure shows the root diagram of the meta-model, where the IfcWallType has references to all maintained concepts described above. IfcWallType is the type of IfcWall. Consequently it enforces the references to all types that describe the concepts defining a IfcWall.

Figure 2. The class diagram of the domain meta-types relevant for IfcWall.

  • Testing
    The domain classes such as IfcWall from the Shared Layer of IFC can now simply be instantiated from the newly developed domain meta-classes. As proof of the semantic equivalence of the generated model and the IFC model of IfcWall serves the comparison between the instances they produce. Those are based on an example contained in the IFC documentation on the buildingSmart website. Both semantic and quantitative metrics were used (e.g. number of objects and links).

Results

The comparison between the instances of the new model instantiated from our meta-model and the IFC standard model in the Testing section shows that instances of IfcWall differ in number of objects and links. However, semantically both instances are effectively the same.

The meta-model has the following advantages and improvements over the IFC standard:
  • Readability and Comprehensibility
    The replacement of complex design patterns with classification resulted in fewer associations and reduction of attributes in the instantiated model. This makes it easier to read and comprehend than the standard IFC model. The reduction in complexity is also facilitated by the redesign of the objectified relationships typical of the standard.
  • Extensibility
    The redesign of the type-object pattern allows the definition of type properties in the domain meta-type layer. An immediate consequence of that is that the number of available wall types can be extended. As demonstrated in the Figure 1, a new type of wall (not present in the current IFC standard) can be created in the domain type layer: The IfcCollapsableWall type represents a wall that can be collapsed. The definition of properties which describe the collapsing behavior is enforced by the type-instance relationship.
  • Type-Safety
    The IFC standard is not type-safe because of type-to-object linking at instance level, as shown on the right side of Figure 1. The multi-level modeling paradigm removes this weakness by using the instantiating capabilities of the object-oriented development approach.

Thursday, June 29, 2017

SysML2Python Code Generation

By Markus Schäffer and Matthias Bauer

Introduction

The Object Management Group's (OMG) Systems Modelling Language (OMG SysML) can be used to describe various kind of systems. After modelling a system, one scenario is that software engineers use these models to write any form of software. For example, software experts may write code for a system that has to be developed. Another scenario is that one wants to simulate the system, e.g., to learn something about its implications. When starting to write code, soon the problem arises how to reuse the work done in the modelling phase. One possible way are Model-to-Text transformations. Model-to-Text transformations, as a part of Model Driven Software Engineering (MDSE), enable to generate code from models. Thus one can save time in the development phase, since software engineers do not have to start writing code from scratch.
Hence, to address the problem of reusing SysML models for further work, a model driven code generation approach was used in this work. In particular, a code generator is proposed to translate different SysML diagram kinds into respective Python code. This code generator relies on the Eclipse Modelling Framework (EMF) and the SysML implementation of the UML and SysML modelling tool Papyrus. In order to show the practical usage of the code generator an example of a coffee machine serves as an input for our SysML2Python code generator. As a result with the SysML2Python code generator, we were able to successfully generate Python code out of our supported SysML diagram types. These supported diagram types are the Block Definition Diagram (BDD), Internal Block Diagram (IBD) and Parametric Diagram (PAR).

SysML Diagram Types (dark blue: Supported by SysML2Python Code Generator)

   Used Technology

  • Python, which is an universally applicable, object-oriented interpreter for high-level programming
  • Object Management Group (OMG) Systems Modelling Language (OMG SysML), which is a general-purpose language for systems engineering applications
  • Xtend, which is a programming language and was used to write the SysML2Python code generator
  • Papyrus, which is a tool for graphical modelling of UML, SysML and other modelling languages

Implementation

Our SysML2Python code generator takes an .uml file as input file, which holds the SysML Features attached with Stereotypes in form of a tree, and generates one Python module as output file.
In Papyrus, the information of the modelled system is represented in a single file, regardless of the number of actual modelled diagrams. For example, in case of an Internal Block Diagram the information of its own and its base the Block Definition diagram is stored in a single .uml. This file serves as input for the code generator.
The code generator generates one output file (the Python module of the .uml file). The main reason for a single file is that the generated code can easily be imported by another Python program. For each element in the .uml file the type of the element is queried first (via use of the instanceof operator). Then, the corresponding method is invoked, which holds the individual structure for each type. The next code snippet shows this structure. The polymorphic generateElement method invokes the corresponding method of the type of the actual element (see line 5 in the next code snippet).

fsa.generateFile('''<<ModelName>>.py''', '''
"""GENERATED BLOCKS"""
<<FOR EObject obj : root.eContents>>
    <<IF obj instanceof org.eclipse.uml2.uml.Class>>
        <<generateElement(obj)>>
    <<ENDIF>>
<<ENDFOR>>
''')

Conclusion and Future Work

The objective of this project was to generate Python code from SysML Block Definition-, Internal Block- and Parametric Diagrams. The proposed solution called 'SysML2Python Code Generator', which uses the Eclipse Modelling Framework, Xtend and Papyrus. allows to generate code from .uml files that contain a SysML model. The generated code can easily be imported by other Python applications and has great potential to be used as a basis for further programs. A specially interesting application would be to use the generated code as a base for simulations of SysML models. Nevertheless, further study on generating code from SysML equations is needed to address the issue of using more complex equations in parametric diagrams (e.g. to have built-in functionality to simulate the behaviour of the system over time).

Visual Profiling of Entity Models

Intro
Using models is a powerful strategy for understanding concepts, that would otherwise be hard to grasp. With models, it is possible to provide an intuitive level of abstraction for a magnitude of engineering tasks. For this reason, in Model Driven Engineering, models are even seen as an integral approach to creating systems, not only to understanding them. However, the adoption of MDE both in educational and professional environments has been slower than expected. One survey conducted among professional software developers suggests, that the majority of developers does not rely on modeling tools for their work.

Empirical studies suggest that the lack of modern tools and tedious installation processes are among the reasons for the slow adoption. Using web technologies rather than traditional modeling frameworks for creating modeling tools may be one approach to solve these problems. In this work, we provide a small example for such a web-based modeling approach.

The example application provides an interactive visualization of entity models and their dynamic (growth) behavior over time, as systems typically manipulate its underlying data during runtime.
By including various runtime aspects of entity models, we combine design time and runtime information into a single visual representation. Traditionally, this incorporation has been difficult. This is mostly due to the technological limits of EMF, which is why our approach will use the Javascript libraries D3.js and emf-json.

Architecture

The architecture of our software consists of several steps to ensure an identical visual representation inside the web browser.

  • The architecture pipeline starts with concrete models, in our case entity models, that describe a running system or a database.
  • Snapshots are generated over time to collect data about the behavior and changes made within the system. They provide information which can be the decrease in classes in general, deletion of relationships between those classes or an increase in attribute values.
  • These snapshots, including the model, are transformed from their EMF representation, which is an XMI file, to corresponding JSON representations. This transformation is done via the emfjson-jackson framework. For our purposes, ten snapshots are provided for the final visualization.
This serialized JSON object is an example on how such a transformed entity looks like after this step has been done.
  • After the previous step we now have ten snapshots and a model that contains information on how the entities relate to each other. To be able to visualize these snapshots inside a web browser with the help of D3.js, a custom mapper was implemented that helps with transforming the JSON data in valid D3.js data. The mapper builds JSON representations consisting of nodes and links.
  • With the help of ecore.js we can parse our JSON Ecore models and create a corresponding structure that can be visualized accordingly.
This is an example of how a node looks like. It has an ID to be referenced when creating links and various information about the entity itself. The group describes membership of the entity, e.g. if it is part of a containment or a supertype relationship.
A link contains source and target nodes and the type of relationship they reference.
  • The last step consists of the actual interface we needed to implement to be able to interact and view the transformed graph inside a web browser.

Visualization

The idea behind the visualization by a D3 force graph is to get a visual representation of different aspects like containment, inheritance, references and others. The graph objects and forces are easy to adapt with custom functions, and therefore, are suitable for representing information about instances of a model.

For the calculation of the distance metric the radii of the objects serve as the initial value, which means that a link can never be shorter than the combined radii of two connected nodes. To this we add a “base distance” which is the same for all links. This base is multiplied by a variable, which is selected, based on the link type.
The formula for the length of a link is defined as:
where is the length of the link, is the radius of a certain node , is the base distance  and is the link type based multiplier.


We provide the functionality to filter out certain link types, to make it feasible to focus only on some links, which may be helpful to analyze a particular aspect of the input data.

In addition to the graph representation of the Entity Model, we provide a list of all basic attribute values. This list is displayed when selecting a specific node and consists of a set of descriptive statistics for all numeric and enumerative values.  Statistics for numeric values include the value range (min, max) and average value. For enumeration types, we provide the distribution of values within the model. This information helps to quickly grasp the types of data contained in the selected class and provides further evidence about unexpected outliers and other anomalies, which might indicate an unintended system behavior (e.g.,  system failure).


Conclusion

The evaluation provides an indication of the usefulness of our approach by making a case for a number of important visualization aspects and by providing a mid-sized modeling example. Along this key result, our main contribution was not a new way of visualizing entity models. It was the many benefits that can be gained by using web technologies. On the user-perspective, benefits include the disappearance of an installation or manual update process, as well as creating inherently intuitive and clean visualizations. For the development perspective, which is crucial for the modeling community, we experienced a high rapidness of prototyping and developing for this modeling application mostly attributed to JavaScript, ecore.js and D3.js.

Future Work

The field of modeling and graph visualization offers many opportunities in adapting software solutions to web based approaches, in order to achieve the benefits that were described above. The proposed visual profiler for entity models only touches the surface of what is possible with modern web technologies. It is extensible in a number of ways.

Minor improvements

One minor improvement could be to introduce zooming as another mode of interaction, allowing for larger diagrams to be drawn and different levels of granularity (e.g. package level - class level - object level). Another improvement lies in the extension of considered attributes. Apart from numeric and enumerative attributes, all primitive data types may be considered.

Major improvements


The proposed minor improvements however do not capture the bigger picture of web based modeling development in the future. The key benefit of web technologies is interaction. Hence, one possible major improvement of the framework could be to add the functionality of interactively changing the diagram, e.g. by adding new classes or references. This is feasible with ecore.js, which allows the modification of Ecore models in the web browser and could be a promising alternative for some use cases to replace traditional editing environments like Eclipse (at least for non-experts).

Wednesday, April 12, 2017

Tutorial: Language Design & Model Execution with xMOF and GEMOC Studio

By Tobias Ortmayr and Tanja Mayerhofer

Introduction

This tutorial demonstrates how to use xMOF in GEMOC Studio for developing executable domain-specific modeling languages (xDSMLs) and executing models. For this, it will show you how to make the predefined FSM language, a simple Ecore-based language for defining finite state machines, executable with xMOF, and how to execute and debug FSM models. To achieve this, you will learn how to perform the following steps:
  1. Setup GEMOC Studio with xMOF
  2. Import the (not yet executable) FSM language
  3. Create an xMOF project for the FSM language
  4. Define the execution semantics of the FSM language with xMOF
  5. Generate code for the FSM xMOF model
  6. Create an xDSML project for the FSM language
  7. Create an animator project for the FSM language
  8. Launch the modeling workbench for the FSM language
  9. Execute an FSM model

The complete FSM example is also provided together with the xMOF component of GEMOC Studio. In the end of the tutorial, you find instructions on how to install the example.

1. Setup GEMOC Studio with xMOF

For setting up GEMOC Studio, download the latest version of GEMOC Studio from gemoc.org. The download will deliver a compressed zip or tar.gz archive. Decompress this archive into a directory of your choice and ensure you have full read and execute permissions for this directory. Start GEMOC Studio by running GemocStudio.exe on Windows or GemocStudio on other platforms.
xMOF is provided as an additional component of GEMOC Studio. To install it, open the menu Help and select Install Additional GEMOC Components. Select from the category Alternative GEMOC based Engines the component GEMOC xMOF Engine.


After selecting the component GEMOC xMOF Engine, hit the Finish button. Confirm the Install and Install Details dialogs by hitting Next, read and accept the license agreement and hit Finish. Confirm the warning about installing unsigned content and restart GEMOC Studio.

2. Import the FSM Language

The FSM language is a simple language for defining finite state machines. Its abstract syntax is defined by an Ecore model. For graphically visualizing FSM models, a Sirius-based editor is also provided for the language.
We will see in this section how we can import the EMF projects implementing the FSM language and have a look inside these projects.

Download the FSM Implementation Projects

The EMF projects implementing the FSM language can be downloaded as an archive file fsa-tutorial.zip from modelexecution.org.

Import the FSM Implementation Projects

For importing the downloaded projects, open the menu File and select Import... In the opening Import wizard, select General / Existing Projects into Workspace. Chose the downloaded archive file fsa-tutorial.zip under the option Select archive file and select all projects located in the directory language_workbench.


Abstract Syntax

FSM models are simple I/O state machines. The abstract syntax of the FSM language is defined by the Ecore model fsm.ecore located in the imported project org.modelexecution.xmof.examples.fsm.


As you can see from the Ecore model, a finite state machine (FSM) is a set as of states and transitions. One state serves as initial state. Each transition has exactly one source state and exactly one target state. In addition, each transition defines an input String and an output String. For each state, the inputs of outgoing transitions must be distinct to avoid non-deterministic state machines.

Concrete Syntax

The graphical concrete syntax for visualizing FSM models is defined by the Sirius viewpoint specification model fsm.odesign contained by the imported project org.modelexecution.xmof.examples.fsm.design. It depicts states as circles and transitions as edges with their input / output Strings as label.


The example shows a simple finite state machine that accepts the input String “HELLO!” and produces the output String “WORLD!”.

3. Create an xMOF Project

To make the FSM language executable, we have to first create a new xMOF project for the FSM language.
To create a new xMOF project, open the menu File and select New &gt Other.... Select in the category xMOF the entry xMOF Project.


In the appearing dialog New xMOF Project, you have to provide the name of the xMOF project and the name of the executable language that is going to be developed.
For the FSM example, we chose the following names:
  • Project name: org.modelexecution.xmof.examples.fsm.xmof.dynamic
  • Language name: FSM
Confirm the input by hitting the Next button.


On the next page Ecore Metamodel File, you have to select the Ecore model defining the abstract syntax of your language. For this, click on Browse Workspace, unfold the project org.modelexecution.xmof.examples.fsm, select the file fsm.ecore and hit OK. The content of the Ecore model will then be displayed in the wizard page.
As last step you have to select the main class of your Ecore model. This class will serve as entry point for the execution of FSM models. Select the class FSM as main class and hit Finish.


The wizard created for you the new xMOF project org.modelexecution.xmof.examples.fsm.xmof.dynamic containing a new xMOF model fsm.xmof. This xMOF model provides configuration classes for all classes of the FSM Ecore model and will be used in the next step for defining the execution semantics of our FSM language.


4. Define the Execution Semantics of FSM with xMOF

In this step, we will define the execution semantics of the FSM language. This is done in the created xMOF model fsm.xmof. We will have to define the following components common to the execution semantics of xDSMLs:
  1. Dynamic elements defining the runtime states of models
  2. Input parameters accepted for the execution of models
  3. Behavior of the model elements

Before we go into the details on how to define these elements for FSM, we will first have a look at the desired execution behavior of FSM models.

Desired Execution Behavior

When executing an FSM model we want to process a sequence of input Strings and determine the output String produced by the finite state machine. For doing that, it is checked for each String in the input sequence whether one of the outgoing transitions of the currently active state can process it. A transition can process a String when it is equal to the input String defined by the transition. A finite state machine starts with the initial state as first active state. If a transition can process the current input String, the transition is fired. When a transition is fired, the transition output String is added to the output String starting with an empty String, and the target state of the transition is set as the new active state.

4.1. Define Dynamic Elements

To achieve the desired execution behavior we need a way to define the currently active state of a finite state machine as well as the output String of a state machine. In addition, we also need to store information about the accepted input sequence of Strings. This is referred to as the runtime state of a finite state machine.
To define the runtime state of an FSM model, we therefore extend the configuration class FSMLConfiguration with a reference currentState to the State class, and the multi-valued String attributes producedSeq and acceptedSeq.


4.2. Define Input Parameters

Input Elements

The input processed by a finite state machine is an arbitrary sequence of input Strings. To enable the user of the FSM language to define such an input String sequence, we introduce the class Input into the xMOF model owning the multi-valued String attribute inputSeq. Note that the property unique of this attribute has to be set to false to allow duplicate elements in the sequence.


Input Parameters

Finally, we have to define that an input String sequence, i.e., an instance of the newly defined class Input, has to be provided for executing an FSML model. To do that, we have to add an input parameter to the main operation that was automatically added to the main class of our FSM language FSMConfiguration.
To add this input parameter right-click on the operation main and select New Child > DirectedParameter. Change the name of the input parameter to input and set its type to Input.


4.3. Define Behavior

To define the above described execution behavior of finite state machines, we have to define four operations and their behavior:
  1. The main operation of the configuration class FSMConfiguration serving as entry point of the execution.
  2. The run operation of the configuration class FSMConfiguration defining the behavior of finite state machines.
  3. The process operation of the configuration class StateConfiguration defining the behavior of a state when processing an input String.
  4. The fire operation of the configuration class TransitionConfiguration defining the behavior of a transition when firing.

Add Operations

To add a new operation, right-click on the respective configuration class and select New Child > BehavioredEOperation. Set the name accordingly and add appropriate parameters.


Create Activities

With xMOF, the behavior of operations is defined with UML activities. To create the activity defining the behavior of an operation, simply double-click on the operation. The activity will be created and initialized with parameters corresponding to the parameters defined for the respective operation. For instance, by double-clicking on the main operation, an activity named main_FSMConfiguration is created.


Define Behavior of Activities

Now we can define the behavior of the created activities. Double-clicking on an activity or operation will initialize and open the corresponding activity diagram. We will start with the main operation.


The palette on the right provides tools for the creation of activity nodes and activity edges. xMOF is based on the UML action language. Detailed descriptions of action types and other UML node types can be found in the UML specification.
The modeling of the main activity is covered in detail in this tutorial. For the other activities only the final activity diagrams are shown. Information on how to install the complete example are given in the end of the tutorial.

main Activity

The main activity has to first set the initial state of the finite state machine as currently active state and then to process the provided input by calling the operation run. Finally, it has to provide the output sequence produced by the run operation as output of the finite state machine.
For doing this, we first need to add a Read Self Action named read fsm to the activity. This action will retrieve the executing FSM element. Select the Read Self Action element in the tool palette and click on the diagram. In the appearing dialog, enter the name read fsm and click OK.


In the same fashion, we create the remaining needed actions. To access the initial state of an FSM, we define a Read Structural Feature Action called read initialState and set its property Structural feature to initialState. To set the retrieved state as currently active state, we furthermore create an Add Structural Feature Value Action named set currentState and set its property Structural feature to currentState. To call the operation run, we define a Call Operation Action named call run and set its property Operation to run. Furthermore, to pass the executing FSM element on to these actions, we create a Fork Node.
Use the properties view to set the properties Structural feature and Operation.


Now we can connect the created activity nodes with object flows and control flows. To add a new flow, select the required flow type in the tool palette and then click on the nodes you want to connect.
To pass along the executing FSM element, we need to connect the output of the read fsm action with the created fork node and the fork node with the target and object inputs of the actions call run, read initialState, and set currentState. Furthermore, the initial state retrieved by the read initialState action has to be provided to the value input of the set currentState action. Finally, the provided input parameter value has to be passed on to the run operation. All of these flows are object flows.


However, these object flows cannot ensure that the run operation is invoked only after the currently active state has been set to the initial state of the finite state machine. Thus, we also need to define an additional control flow from the set currentState action to the call run action.
The final main activity looks as follows:


run Activity

The run activity reads the input String sequence provided by the input parameter value and then processes each element in the input String sequence by calling the process operation of the current state. The iteration over the input String sequence can be defined with an Expansion Region. The activity nodes contained by the expansion region are executed for each element of the provided input String sequence.


process Activity

The process activity determines for the current state whether one of its outgoing transitions can process the currently processed input String, i.e., whether one of its outgoing transitions defined the String as processable input. If such a transition is found, this transition is fired by calling its fire operation.


Note that for the outgoing control flow of the decision node, a guard has to be defined. This has to be done in the tree editor. Switch to the tree editor by clicking on the Selection tab shown in the bottom left corner of the editor. Right-click on the object flow and select New Child > Guard Literal Boolean. Then set its Value property to true using the properties view.

fire Activity

The fire activity of a transition has to perform the following tasks: It has to set the target state of the transition as the new current state of the FSM, add the output of the transition to the produced String sequence, and add the processed input String to the accepted String sequence.


5. Generate Code for an xMOF Model

After the xMOF model has been completely defined, we have to generate Java code for it. To do this, right-click in the project explorer on the xMOF project org.modelexecution.xmof.examples.fsm.xmof.dynamic and select xMOF > Generate Code. The Java code is generated in the src foder of the xMOF project.
Please note that the Java code has to be re-generated whenever the xMOF model is updated.

6. Create an xDSML Project

As a next step, we have to create a GEMOC xDSML project for the FSM language that identifies the FSM language as executable language. The GEMOC xDSML project can be automatically generated for an xMOF project. For this, right-click in the project explorer on the xMOF project org.modelexecution.xmof.examples.fsm.xmof.dynamic and select xMOF > Generate xDSML Project.
The generation of the Java code an the xDSML project can be also achieved in one step by right-clicking in the project explorer on the xMOF project org.modelexecution.xmof.examples.fsm.xmof.dynamic and selecting xMOF > Generate All.

7. Create an Animator Project

After completing the previous steps, you can already execute FSM models. If you are not interested in animating executing FSM models, you can skip this step and proceed with Step 9.

Desired Animation

During the execution of an FSM model, we want to visualize:
  • The currently active state in red color
  • The String sequence that the FSM has accepted so far
  • The String sequence that the FSM has produced so far

Add Animation Layer

To implement the desired animation, we first need to add an animation layer and corresponding animation service classes to the Sirius viewpoint specification model. For this, open the Sirius viewpoint specification model of the FSM language fsm.odesign located in the project org.modelexecution.xmof.examples.fsm.design. Right-click on the FSMDiagram element and select xMOF > Add Animation Layer. This adds a dedicated layer called Animation to the diagram and initializes the FsmdiagramAnimationServices class.


Extend Animation Service Class

To display the produced and accepted String sequences we need simple methods that concatenate all elements of the sequence to one single String. In addition, the order needs to be reversed as the elements are added in last-in/first-out order during execution.
For this, we extend the class FsmdiagramAnimationServices with two simple service methods as shown below:



Note that after adding the methods you may get some import errors which can be easily resolved with the Eclipse Quickfix feature.

Extend Animation Layer to Highlight the Current State

To display the currently active state in red color, we can use a style customization. In the Sirius specification editor navigate to the Animation layer. Then right-click on Style customizations and select New Customization > Style Customization. As predicate expression for this customization define [self.containingFSM.oclAsType(fsmConfiguration::FSMConfiguration).currentState=self/]. Then right-click on the the style customization and select New Customization > Property Customization (by selection) and set the property values as shown below:


Extend Animation Layer to Display Information on the Accepted and Produced String Sequences

To display the accepted and produced Strings, we create a container mapping called ExecutionInfo in the Animation layer and contained node mappings called AcceptedString and ProducedString as shown below. For these mappings set the property Domain Class to fsm.Fsm and the Semantic Candidate Expression to [self/]. In addition, change the property Child Representation of ExecutionInfo to list.


For the label expressions of the basic shapes of AcceptedString and ProducedString use the following values:
  • ['Accepted String: '+self.getAcceptedString()/]
  • ['Produced String: '+self.getProducedString()/]



8. Launch the Modeling Workbench

Now we have completely implemented the executable FSM language and a corresponding animator, and are ready to execute and debug FSM models. For this, we start the FSM modeling workbench. Expand the Run control in the menu bar and select Run Configurations....


Double-click on Eclipse Application, change the name to FSM Modeling Workbench, and click on Run to start the FSM modeling workbench.


Import the project org.modelexecution.xmof.examples.fsm.samplemodels from the folder modeling_workbench of the downloaded archive file fsm-tutorial.zip into the modeling workbench. For this, open the menu File, select Import... > General / Existing Projects into Workspace, browse to the archive file, select the sample model project, and hit Finish.
The imported project contains the introduced Hello World example and another example defining a finite state machine for traffic lights. To open an example model make sure that you are in the Modeling perspective. The perspective can be changed with the menu Window   > Open Perspective   > Others.
Open the Hello World example by double-clicking on the HelloWorld.aird file. Then, expand the aird file until the FSMDiagram appears. Open it by double-clicking.


9. Execute an FSM Model

To execute the Hello World finite state machine, expand the Debug control in the menu bar and select Debug Configurations...

Double-click on xMOF Executable Model. Change the name of the new configuration to HelloWorld. Select HelloWorld.fsm as the model to execute and HelloWorld.parameters1.xmi as the initialization model. Select the melange language org.modelexecution.xmof.examples.fsm.Fsm and the animator HelloWorld.aird. Finally, click on Debug.


The Hello World FSM model now starts executing. After the execution engine has been started, a dialog Confirm Perspective Switch will appear. Click on Yes and the debugging perspective will be opened.
Interact with the debugging model using the usual Eclipse debug commands. Use the control Step Into from the menu bar to execute the Hello World model step-by-step. The model will be animated showing the currently active state, the processed input Strings and the produced output Strings. The stack trace view shows the next execution step to be performed and the variables view shows the current values of the different model elements.
Below you can see the animation of the model after stepping three times.


Congratulations! You have defined your first xDSML with xMOF.

Getting the Complete Example

The complete FSM example is delivered with the xMOF component of GEMOC Studio. To install it open the File menu, select New > Other... > Examples / xMOF Language Examples / xMOF FSM Language, and hit Finish. All projects implementing the FSM language will be imported in your language workbench.
In the same way you can also import the sample model project. Open the File menu, select New > Other... > Examples / xMOF Modeling Examples / Model Example for xMOF FSM Language, and hit Finish.