## Exercise 02 - Textual Domain Specific Languages
This repository includes the resources of the first task of the MDSD Example "Transportation Network".
This repository includes the resources of the second task of the MDSD Example "Transportation Network".
## Task Description
## Task Description
The main task of the exercise is to create a **metamodel for the domain of transportation networks**.
The purpose of this exercise is to introduce textual **Domain Specific Languages (DSL)** as a tooling for creating models in a model-driven toolchain. We will be using the *Xtext*[^xtext] tool suite for *Eclipse* to create a text-based editor and parser for our **transportation network models**.
To realize that, we use the *Eclipse Modeling Framework* to create the metamodel and afterwards prepare **multiple networks** to test the metamodel. These also double as test models for following exercises.
To do so, complete the following subtasks:
To do so, complete the following subtasks:
1. Create an `Ecore Modeling Project` for your *transportation network metamodel* in your *Eclipse Modeling Tool* instance.
1.**Create** the `Xtext Project`:
- Open the `workspace` with your solution of exercise 1 (the metamodel projects).
- `New...`➔`Other...`➔`Ecore Modeling Project`
- Right-click on your `metamodel project`$\rightarrow$`Configure`$\rightarrow$`Convert to Xtext Project`
- Name the project as you like
- Open the creation wizard with `File`$\rightarrow$`New`$\rightarrow$`Other..` and choose `Xtext Project from Existing Ecore Models`.
- The most important information is the `main package name` (second page) which will be the name of your metamodel and the file name extension of future models.
- One the next page `Add` the `*.genmodel` file of the *metamodel of exercise 1*. Then choose the meta-element that represent the model (e.g. *TransportationNetwork*) as `Entry rule`. Then click on `Next`.
- Provide a `Project name` and `Name` for the new `Language`.
2. Model your metamodel in the `*.ecore` file. Use the editor that should open on project creation. See the **description of the transportation network** for details.
-**Important:** Name the `Extensions` like the *file extensions of your model files* (often the name of the metamodel). This will replace the new *normal* model files (editable inside the tree editor) with the textual model files (editable with the Xtext text editor) inside the Eclipse instance.
2. View the **automatically created *DSL***
- You only need to use the `Class`, `Attribut`, `Enumeration``Reference`, `Composition`, and `Supertype` meta-elements for this example.
- The created Xtext projects will already include a working DSL parser grammar. You can find the `*.xtext` grammar file under the `src` folder of the newly created main project. This grammar file will be the core of your new DSL. In it, you will describe the rules that define the parsing of structured text to our transportation network model elements. To get an overview of the syntax of Xtext rules, please read through this documentation[^documentation].
- Try to design the `Class`es connected by `Composition`s like a tree (containment hierarchy).The root of the tree should be an `Class` that represence your model itself ( for example `Transportation Network`). All classes except a root class should have (at least) one incoming composition. Use `Reference`s for non-containment relationships.
3.**Refine the autogenerated grammar to a usable DSL grammar.**
- Try too specify the properties of the metamodel elements as clear as possible in the property explorer below the diagram (The explorer shows the properties of the element selected in the diagram).
Normally, the automatically created DSL grammar should not be used directly. It is very cumbersome and often lacks additionally needed model limitations and semantics. You should always try to refine it, making the textual syntax easier to use for domain experts. Also, you could add additional semantics to it, like naming conventions or modeling limitations.
3. Create the `Model`, `Edit`, and `Editor` implementation code through the `*.genmodel` file (open the file and right-click on the root element). This will generate the metamodel implementation and an editor plugin for *Eclipse*.
4. Right-click on the model project and choose `Run As...` and then `Eclipse Application`. A new *runtime**Eclipse* instance will open.
1. Create a grammar for a easy-to-use, refined DSL editor based on the transportation networks from exercise 1.
5. There, create a new general `Project` with the `New...` option and a model `*.[your metamodel name]` with `New...`➔`Other...`➔`search for your metamodel name` (Please choose the metamodel's root element as `Model Object` in the following wizard). You should now be able to model your state machine with a *simple tree editor* by opening the file.
2. Remove attributes from the grammar that should be calculated later.
3. Test the editor by recreating your example transportation network models from exercise 1 in a human-readable form.
**The domain you need to metamodel is described as following:**
4. If you want to add more detailed semantics, you can write custom validation code for your parser/text editor under `src/****.validation/***Validator.java`. For example:
The first part of the domain describes the transportation network itself:
- Check if `Road Network` or `Route` connects the same `Location`
- If a `Location` is isolated in the Network
> A `Transportation Network` must have an `identifier` to refer to it in the database of the users. It consists of multiple `Locations` and `Road Networks`. A location can have a `name` and can include multiple `Points Of Interest`. Each point of interest (POI) can include a `name`. There are different types of POIs:
- There is at least one `CompanyWarehouse` in the Network
>
- Give warnings if numbers, like distances, are not plausible.
> - A `Rest Stop` were drivers can take their mandetory breaks.
> - A `Gas Station` which could serve one or more`Fuel Types` like `Petrol`, `Diesel`, and `Electricity`.
4. After this step, you can **build and start** the new DSL text editor.
> - `Warehouses` that could be `Company Warehouses` (owned by the user) or `Customer Warehouses` (Here the `customer name` should be included)
- Right-click on the `Generate***.mwe2` file next to the grammar and choose `RunAs`$\rightarrow$`MWE2 Workflow`, to generate a working parser and text editor for your DSL.
> - Last, there can be `Other` POIs which have a general `type`.
- Right-click on the metamodel project and choose `Run As`$\rightarrow$`Eclipse Application`. A new Eclipse application will open. There, create a new general `Project` and a `*.[your metamodel name]` file in it. You should now be able to model your state machine with the text editor created by Xtext. (You can use `Control + Space` to get a simple autocompletion.)
>
> Road networks must have an `identifier` and a `target` and `source` location. They can be marked as `directed` to allow mono- or bidirectional usage. They also can include the `length` of the network for later fuel calculations. Each network includes multiple, but at least one, `Road`s. Each road must be `identifiable` and also include their `length`, so that later the network length could be calculated.
The second part of the metamodel includes information for the usage of the transportation network:
> The transportation network also includes `Route`s that can be planed for transportation requests. Each route has an `identifier`and can have a `start` location, `end` location and/or a `list of road networks` the route includes. To execute the routes the transportation network also includes `Vehicle`s. These can be free to use (are in the `car park` of the company) or already included in a route. One route is always driven by one vehicle. The vehicle itself must have an `identifier`, `model`, `fuel capacity` and a `fuel type`. They can include a `location` to help their management for routes in case they are free to use.
## How To Run the Base Solution
## How To Run the Base Solution
1.`Import` the `stgroup.mdsd.transportation_network.*` projects in your *Eclipse* workspace.
1.`Import` the `stgroup.mdsd.transportation_network.*` projects in your *Eclipse* workspace and `run` a new *Eclipse* instance.
2. In the runtime *Eclipse* instance `import` the `model_examples` project to inspect and modify the example *transportation network* models.
2. In the runtime *Eclipse* instance `import` the `model_examples` project to inspect and modify the example *transportation network* models.
