How to create a Petri net editor using GMF (Part 3)
In the first and second part of this tutorial you created three models: a model representing the domain, a model describing the graphical elements of a diagram and a model describing the tools to create the elements of that diagram.
Now you are combining all of it to describe our graphical editor. The model that describes the graphical editor basically says: With <some tool> you can create this <some graphical element>, and when you create it, its equivalent in the domain world is <some domain element>. As this model creates a mapping from the different models to the others it is called the Mapping Model.
Once again, GMF will automatically generate the structure of the model for you by combining the three models you already had. The hard part as always is the customization. Let us have a look at the GMF Mapping Model.
Overview of the Mapping Model
As we said before the Mapping Model describes a graphical editor through mappings, so its root element is a mapping. A mapping can have several kinds of children but we will focus on two types: the Top Node References and the Link Mappings.
Top Node References describes the nodes of your diagrams. You have two node types, places and transitions. You goal is to map each Top Node Reference to the elements that correspond to them in the models. The first thing to say about a node is where it is, i.e. its containment feature. In our Domain Model we had created a root element (the Petrinet class) that contained all other elements. Each of these containment relationships are have a name. So, by defining the containment feature of a node we are telling GMF that when it creates a "Node" of type place, it has to put it in the containment relationship "places" (which at an implementation level is represented by a member of the class Petrinet).
A Top Node Reference Contains a Node Mapping. The Node Mapping contains the real mapping towards the other diagrams. The mappings are defined in the Properties view. Finally, a Node Mapping can contain (among others) a Feature Label Mapping. This allows to to show a place attribute, e.g. its name. Here we also say if we want the feature label to be editable.
The Link Mapping describes, as its name says, the links of the diagram. For each link you have to give the corresponding class in the Domain Model, the source of the arc and the target of the arc. Because of this you need to define two Link Mappings, one from places to arcs, and the other from arcs to places. Each of these types of arcs also have different containment features. We'll see the exact configuration in the next section.
Customizing the Mapping Model
As with the other models you have created, it is not necessary to create the model from scratch, GMF can derive the skeleton of the model for you. In the GMF Dashboard you need to click the "Combine" button and follow the instructions. After the combine you'll end up with the model in the figure:
GMF will do its best to create a sound model but sometimes it fails at it. The first thing to do with you model is to check that the nodes are mapped to the right tool (in the Tooling Model), to the right Figure descriptor (in the Graphical Def Model) and to the right element in the Domain Model. Here are the detailed instructions.
- In the Mapping model, select the places Top Node Reference. In the Properties view, check that the containment feature is "Petrinet.places:Place"
- Under the places Top Node Reference, select the Node Mapping. There are three sections, "Domain meta information", "Misc", and "Visual representation".
- Make sure that Element (in section "Domain meta information") is set to the class Place in you Domain Model.
- Set Diagram Node (in section "Visual representation") to "Node Place (PlaceFigure)"
- Set Tool (in section "Visual representation") to "Creation Tool Place"
- Repeat steps 1 and 2 for the transitions Top Node Reference.
- The next step is to modify the Link Mapping. Select the Link Mapping and open the Properties view. Make it look like the figure:There is a bug in GMF (at least in this version) that makes that your updates in the Properties view are not properly reflected in the model. You need to save, close and reopen your model to see the changes applied.
You have just created your arc first arc.
- The next step is to create the second arc. First you create a new Child of type Link Mapping under the Mapping node of your Mapping Model.
- Then you need to proceed exactly as before but this time set the "Containment Feature" to Transition.incomingArcs, and invert the source and target of the step 4. This will create the outgoing arcs. At a diagram level, you are telling GMF to use the same tool (by tool we mean the little button in the generated editor that allows to create arcs) that was used for the creation of the outgoing arcs.
Generating the Diagram Editor Code
In the same way that we created a Generator Model for our Domain Model, we need to create a Geneartor Model for our Diagram Editor. To proceed with the generation you need to have the following things in your workspace:
- All the models we have created until now: Domain Model, Domain Gen Model, Graphical Def Model, Tooling Def Model, and Mapping Model.
- The generated code for the Domain Model and the generated code for the Edit Code. Both can be generated from the Domain Gen model. Just open the Domain Gen Model, right click on the root element and from the contextual menu, choose "Generate Model Code" and "Generate Edit Code"
Now, first you need to generate the Diagram Editor Gen Model. Go to the GMF Dashboard, and click the Transform link next to the Mapping Model. GMF will automaticall create the Diagram Editor Gen Model in your workspace. The file has the extension "gmfgen". You don't need to modify this file, you can directly click on the "Generate diagram Editor" button (also in the GMF Dashboard) and your Diagram Editor will be generated.
The code generator created a new project in your workspace whose name ends with ".diagram". To launch your editor you just need to right click on the Project and select Run As → Eclipse Application. In the application that is launched, create a new project. Right click the project and go to New → Other.... In the wizard you will find Petrinet Diagram under the category "Examples". Select it and you will be able to edit your diagram.
In this tutorial we have seen how to create and customize the Mapping model, and how we can generate the code from it. However, for some strange reason, your Diagram Editor won't create incoming arcs to your transitions. In the next part of this tutorial, you will see how to fix that problem and also understand (a little bit at least) of how the code of the diagram works.
The last part of the tutorial is available 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!