How to create a Petri net editor using GMF (Part 1)

There are several other tutorials on the internet about the use of GMF. The main problem that I found when using them is that they start from models that are well suited for GMF, i.e. generating a working graphical editor from them is almost automatic. However, my experience is that, if you do not know the workings of GMF, it is highly probable that the creation of your graphical editor from your model won't be as straightforward.

I firmly believe that your domain model should represent the domain, or be tailored to the goal you have with it. You should not change the model to fit the tool's way of doing things, but make the tool fit to your goals. Hence, in this tutorial we start from a model that does not fit GMF paradigm and adjust GMF to deal with it. By not fitting the GMF paradigm we mean that the user will have to slightly customize the generated code and automatically derived models to have a working editor. 

In the part 1 of this tutorial we will give a short overview of GMF and all the models that will be generated. Then we will briefly explain our Domain model, and finally we will describe the generation of the Domain model code with the help of EMF.

Pre-requisites

This tutorial assumes the following things about you:

  • You are familiar with the notion of meta-model and are able to create meta-models using EMF. If you are not, there is a very good tutorial at vogella.com
  • You have Eclipse modeling tools (this tutorial is based on Kepler) with the following plugins installed:
    • Graphical Modeling Framework Tooling (from the Eclipse marketplace)

Overview of GMF

As its project description says, GMF "provides a model driven approach to generating graphical editors in Eclipse". This means that we will be starting from a platform independent model (PIM) that represents our domain (this is the Ecore model). Then, by means of model transformations, we will derive new models from it. From the newly generated models, we repeat the process by generating and deriving other models until eventually we get a completely platform-specific model, in our case, the Java code. You can see the complete definition a a Model Driven Approach here.

To guide user to the generation of all these models and transformations, GMF provides the GMF Dashboard. You can open the GMF Dashboard by opening the menu Window → Show view → Other.... It is depicted in the following picture.

The GMF Dashboard - You can open it by opening the menu Window → Show view → Other...

 As you can see in the image, everything starts from the Domain Model in the center. From it you can derive three models. The Domain Gen Model, the Graphical Def Model and the Tooling Def Model. Let us see what each model is for.

The Domain Gen Model

Extension: .genmodel

The Domain Gen Model is an intermediate model between the actual code and your platform independent model. This model describes the code generation. It can also be seen as the parameters that are given for the code generation. For example, you can set the base package of your generated code, you can decide if a class is going to be generated or dinamically simulated by EMF, or also, say on which directory the code will be generated. Personally, the only thing I set in this model is the base package name.

From the Domain Gen Model you can generate code for the following things:

  1. Generate Model code This generates a new project that contains an Eclipse plugin that represents the domain layer of the application.
  2. Generate Edit code This generates a new project that contains an Eclipse plugin that represents an UI independant part of the model editor. We need to generate this for GMF to work.
  3. Generate Editor code This generates a new project that contains an Eclipse plugin that represents the UI dependant part of the model editor. This project will allow you to edit and view instances of your model using several common viewers.

The Domain Gen Model is not GMF specific, but EMF specific.

The Graphical Def Model

Extension: .gmfgraph

This model describes the graphical elements that you will find in your diagram. For example, a Petri net diagram contains places (ellipses or circles), transitions (black rectangles) and arcs (directed polylines). Hence, for a Petri net, this diagram says (in plain English): in the canvas there are two kind of nodes, one is a rectangle and the other is an ellipse, there is also one connection that is a polylined that has an arrow head on the target side. Note that this diagram does not know about classes in the domain model, it is just a geometrical description of what can be found in the canvas.

The Tooling Def Model

Extension: .gmftool

The Tooling Def Model describes the palette and the tools that will be used for the creation of the diagram elements. For our example, to create a Petri net diagram we need a tool to create places, transitions and arcs. As the Graphical Def Model, this diagram does not know about the domain model, this is a just a description of the creation tools that will be available in our diagram. Note that this diagram describes the graphical representation of the creation tools, i.e. it describes which icon to use when displaying the button and also which title to put to the button.

The Mapping Model

Extension: .gmfmap

Even though the Graphical Def Model and the Tooling Def Model are derived from the Domain Model, the three models are completely orthogonal. The Mapping Model links them together. In plain English, the Mapping Model says that: An ellipse in the Graphical Model is the representation of an instance of a Place (i.e. a class in the Domain Model) and is created using some creation tool described in the Tooling Def Model.

The Domain model

As starting point we will take the following model:

Metamodel for Petri nets.

In this model, a Petri net represents has places and transitions, and each transitions contains two sets of arcs: incoming and outgoing. Each Arc has a Place and a Transition, but the source and target of the arc depends on which container of the Transition contains it.

This model is particularly well tailored for applications where you need to loop over transitions, and for each transition you need to loop over incoming and outgoing arcs. This models also features only one Arc class that represents either an incoming or an outgoing arc, which is a natural modeling choice (IMO). It is also very good to automatically generate a textual language with Xtext

Code generation

If you already know how to generate domain code from an EMF model you can safely skip this section. To generate a GMF graphical editor, you need to generate de Model Code and Edit Code from the Domain Gen Model.

Once you have defined your Domain Model, you need to derive the Domain Gen Model. You can do it easily from the GMF Dashboard by clicking the "Derive" button to the left of the Domain Model box. As we said earlier, it parametrizes the creation of the code. Four our purpose we only need to modifiy two parameters: the Base Package and the Prefix. To modify those parameters you need to do the following:

  1. Open the "Properties" view (Go to the menu: Window → Show view → Properties)
  2. Open your Domain Gen Model.
  3. In the window, under the root element, select the first child while the Properties view is open.
  4. In the Properties view, enter a valid Base package. The Base package has to be a valid Java package name. All generated classes will be in subpackages of the Base package.
  5. In the Properties view, enter a valid Prefix for the generated factory classes (it must be a valid Java identifier, starting with a capital letter). The factory classes in your model code will be prefixed with the name you enter here.

Conclusion

At the moment, your workspace has to contain the following projects.

  • An EMF project containing the following
    • Your ecore model and its corresponding ecorediag model.
    • Your Domain Gen Model correctly configured.
    • The Domain code generated from the Domain Gen Model.
  • A project containing the EMF Edit project.

In the next part of this tutorial we will learn what to customize in the different models to have working Petri net editor.

You can check the next part here. If you like these tutorials and would like to get them on your email, please subscribe using the side bar form. Also, do not hesitate to ask questions and give feedback in the comments!

tweet: