A hands-on introduction to(meta-)modelling with eNeo(eMoflon::Neo), by @Anthony A.
eMoflon::Neo(referred to as just eNeo as from now) is part of the eMoflon tool suite. eNeo supports model management as a layer over Neo4j, a fairly well-known graph database.
This handbook focusses on(meta-)modelling as a first model management task. To fully enjoy the ride, you should have very basic knowledge of Eclipse and Java, a rough idea of what metamodelling is, and perhaps some prior experience with Neo4j.
The Example: First Orchard(Obstgarten)
For a long time my son’s favourite board game was Obstgarten. The game consists of various parts including the cute villain — a hungry raven who wants to eat all the fruit in the orchard, various fruit trees with fruit on them, a pathway leading to the garden, a fruit basket, and a dice with the raven and colours for the five fruit trees as its six sides(see below).
The aim is to pluck and collect all fruits from the trees before the wicked raven reaches the orchard and gobbles them all up. I love this game as it reminds me of a similar contest over sweet guavas between my family and a well-organised host of fruit bats(we usually lost).
The rules of the game are that the raven has to proceed along the path to the orchard taking one step at a time. The path consists of a number of segments; there are five in the picture above. You play against the raven and can collect exactly one fruit from a fruit tree at a time.
Throwing the dice decides who gets to make the next move: if you get the side with the raven then it takes the next step along the path, if you get a side indicating one of the fruit trees then you collect a single fruit from this tree and place it in your basket. The game gets more exciting as it progresses because the raven’s chances continuously improve — while it only has a chance of one in five to take a step at the beginning, as more and more fruits are collected your chances start reducing as the dice now has to show the fruit trees that still have fruits on them. For example, as soon as all plums have been collected, getting a blue side of the dice doesn't help you anymore.
We’ll be using Obstgarten as an example of a configurable system that we want to understand and explore by modelling it. Some interesting questions related to game design include:
What are the chances of winning against the raven with the configuration shown in the picture(how many games do we win from say 100)?
How does this change when we vary the number of segments of the path?
How does this change when we vary the number of fruits on each fruit tree?
How does this change when we reduce the number of fruit trees and increase the number of sides of the dice showing the raven?
Installation and Setup
To install eNeo follow the few steps described here. If you have any problems or questions please create an issue and ask for our help.
A Metamodel for Obstgarten
First steps, workspace setup
In a workspace of your choice, invoke the new project wizard for Java projects by choosing File/New/Java Project. Enter eneo.example.Obstgarten as the name of your project and click Finish to create the project. When prompted to create module-info.java choose Don't Create.
Now choose the src folder in your newly created project and add a new file via File/New/File. In the dialogue that pops up, enter Language.msl as the name and extension of the file to be added. As soon as you confirm the file will be created and a dialogue Configure Text will pop up asking if you want to convert your project to an Xtext project. Agree by choosing Confirm.
The language we’ll be using for(meta-)modelling in eNeo is called eMSL, short for the eMoflon Specification Language. eMSL files are identified by Eclipse via the file extension .msl and can be placed anywhere in a project. As the eMSL editor is based on Xtext — a so called language workbench — some basic support for Xtext editors must be added to the project for things to work(making the project an“Xtext project”).
In the opened Language.msl file, press Ctrl+Space to invoke code completion. From the menu that pops-up, choose metamodel and confirm by pressing Enter. Using Ctrl+Space is generally a good idea when working with Eclipse editors. Typically you get useful suggestions and can avoid tedious typing and avoid silly typos. Enter the following in the file:
metamodel Obstgarten {
}
To the right of the editor you should have by default the Outline which should currently contain exactly one element representing your metamodel. While the outline is already quite helpful, we’ll also be working a lot with a dedicated visualisation for models and metamodels. To open the visualisation choose Window/Show View/Other… then type in PlantUML in the Show View dialogue that pops-up. This should reduce the choice of views to exactly three views related to PlantUML(see the image below and to the left). Choose the first one and confirm with Open.
Choose+open the PlantUML view
Our recommended layout for working with eNeo
We recommend placing the PlantUML view to the right of your outline. Just choose the PlantUML tab and literally pull it to where you want the view to reside. Your workspace should now roughly resemble the screenshot above and to the right.
Metamodelling means language definition, i.e., we are creating a language that describes all possible Obstgarten“models”, including what is depicted above. A metamodel describes the allowed structure of models of a language(referred to as its abstract syntax). While a metamodel is an important part of a modelling language, it is not the language itself as other parts are missing such as additional constraints not covered by the metamodel, a suitable notation(also called concrete syntax) for the language, and its semantics.
The Example: First Orchard (Obstgarten)
Installation and Setup
A Metamodel for Obstgarten
metamodel Obstgarten {
}