⚠️ The examples in this repository are currently work in progress ⚠️

This repository contains a couple of examples that show various aspects of the modelix platform. Not all features of modelix are shown here so this is not a complete demo of everything modelix can do. The primary focus of the examples is to show how you can use modelix to work with language and models defined in MPS outside of MPS using plain Java or Kotlin. None of the examples try to reuse editors defined in MPS, if your goal is to reuse MPS editors as is then modelix itself ships with a projector integration to achieve this.

While all the examples use the same language defined in MPS they aren't meant as one complete example but rather as individual parts. The purpose of the examples is to give inspiration of what is possible with modelix and make you think and envision your own use-cases.

The repository is a single gradle project to make building everything at once easy. The examples are then organized in the various sub-folders:

To get started with the project we need to set up the gradle project. At the moment most modelix artifacts are stored on GitHub packages. To access GitHub packaged you need to specify your credentials. First of all you will need to generate a personal access token with access to GitHub Packages. The project assumes that your username is available as the variable gpr.user and the token as gpr.key. The easiest way to configure the credentials is copy the example below, paste it into the gradle.properties file in the repository and replace the values with your credentials:

gpr.user=<your GitHub login>
gpr.key=<your personal access token>

Gradle also supports other locations for specifying these properties.

After you have set up your credentials you can build all examples via gradle:

./gradlew build # mac/linux

gradlew.bat build # windows

Once the initial build has completes feel free to edit the project with the code editor of your choice.

The language used in all examples is the same. The language itself is fairly small. It describes a very simplified lecture schedule. The language intentionally doesn't use expressions, creating editors for expressions by hand is very cumbersome and at the time where these samples were created modelix has no support for generating these editors for you. The main concepts of the language are:

• Room: where lecture are held. Each room has a maximum capacity of students, a name and some additional properties.
• Lecture: Have a name, some description and reference a room where they are held. And also have a schedule which determines when they are held and if they repeat through the whole semester or are a one time lecture.
• Student: A student with a name and birthday.
• Assignment: Lecture assignments for a single student.

Some concepts are contained a root node like a Rooms container to make structuring the editors in MPS easier:

  classDiagram
      class Rooms {
        <<root>>
      }
      class Courses {
        <<root>>
      }
      
      class Students {
        <<root>>
      }
      
      class LectureAssignments {
        <<root>>
      }
      
      Rooms *-- Room : 0..n
      Courses *-- Lecture: 0..n
      Lecture .. Room: 1
      Lecture *-- Schedule: 1
      OneOff <|-- Schedule
      Recurring <|-- Schedule
      Schedule *-- DateAndTime:1
      Students *-- Student: 0..n
      Student *-- DateAndTime:born [1]
      LectureAssignments .. Student: 1
      LectureAssignments *-- Assignment: 0..n
      Assignment .. Lecture:1

In oder to be able to work with the metamodel / structure of the language outside of MPS we need to generate an API that is usable outside of MPS. This API is generated with the api-gen plugin from modelix. The plugin takes an MPS language definition and exports it into a Java API that wraps around the metamodel independent model-api from modelix. The wrapper is than metamodel specific and give you easy access to the instance of your language.

The generator is configured in the University.Schedule.api with an ApiDefinition. When the model that contains the ApiDefinition is rebuild it will generate Java classes for the languages that are referenced withing it.

You can find the generated code within the repository at mps/solutions/University.Schedule.api/source_gen The generated Java code is then not compiled within MPS but using a separate gradle build here. The generated code has no dependency into MPS at all but depends on org.modelix.mps.api-gen:runtime which contains a couple of base classes to make the code generator implementation less convoluted and easier to maintain.

For instance accessing the rooms on the Rooms root node and then reading the name of the Room using the modelix model api directly would look like this:

val iNode : INode = ...
iNode.getChildren("rooms").forEach { it.getPropertyValue("name") }

You can see that this is quite error-prone because every access to a child role or property is just a string. If you have a typo or the structure of the language changes you will only notice it at runtime.

Using the generated API the same code looks like this:

val iNode : INode = ...
val rooms = MPSLanguageRegistry.getInstance<Rooms>(iNode)
rooms.children.rooms.forEach { it.properties.name }

The code generator has exported the language definition, and we can use to write type safe code that works with the models. For properties and children we now have attributes in the generated classes and if somebody renames a property or child-role the compiler will tell us. Of course the MPSLanguageRegistry.getInstance<Rooms> would throw an exception if our iNode instance isn't a Rooms instance.

The generate class for a the Room concept:

concept Room extends BaseConcept                                                                                                                                                          
             implements INamedConcept                                                                                                                                                     
                                                                                                                                                                                          
instance can be root: false 
alias: <no alias> 
short description: <no short description> 
 
properties: 
maxPlaces : integer
hasRemoteEquipment : boolean         
 
children: 
<< ... >> 
 
references: 
<< ... >>                                                                                                                                                                              

package University.Schedule.structure;

/*Generated by MPS */

import jetbrains.mps.lang.core.structure.BaseConcept;
import jetbrains.mps.lang.core.structure.INamedConcept;
import org.modelix.mps.apigen.runtime.INodeHolder;
import org.jetbrains.annotations.NotNull;
import org.modelix.model.api.INode;
import org.jetbrains.annotations.Nullable;

/**
* Generated for http://127.0.0.1:63320/node?ref=r%3Adfa26643-4653-44bc-9dfe-5a6581bcd381%28University.Schedule.structure%29%2F4128798754188010580
  */
  public class Room extends BaseConcept implements INamedConcept {

public class Properties extends BaseConcept.Properties implements INodeHolder, INamedConcept.Properties {

    @NotNull
    @Override
    public INode getINode() {
      return Room.this.getINode();
    }
    @Nullable
    public Integer getMaxPlaces() {
      String propertyValue = getINode().getPropertyValue("maxPlaces");
      if (propertyValue != null && !(propertyValue.isEmpty())) {
        return Integer.parseInt(propertyValue);
      }
      return null;
    }
    @Nullable
    public Integer setMaxPlaces(Integer value) {
      if (value != null) {
        getINode().setPropertyValue("maxPlaces", Integer.toString(value));
      } else {
        getINode().setPropertyValue("maxPlaces", null);
      }
      return value;
    }
    @Nullable
    public Boolean getHasRemoteEquipment() {
      String propertyValue = getINode().getPropertyValue("hasRemoteEquipment");
      if (propertyValue != null && !(propertyValue.isEmpty())) {
        return Boolean.parseBoolean(propertyValue);
      }
      return null;
    }
    @Nullable
    public Boolean setHasRemoteEquipment(@Nullable Boolean value) {
      if (value != null) {
        getINode().setPropertyValue("hasRemoteEquipment", Boolean.toString(value));
      } else {
        getINode().setPropertyValue("hasRemoteEquipment", null);
      }
      return value;
    }
}
public class Children extends BaseConcept.Children implements INodeHolder, INamedConcept.Children {

    @NotNull
    @Override
    public INode getINode() {
      return Room.this.getINode();
    }
}
public class References extends BaseConcept.References implements INodeHolder, INamedConcept.References {

    @NotNull
    @Override
    public INode getINode() {
      return Room.this.getINode();
    }


}

private final Properties properties;
private final Children children;
private final References references;
public Room(INode node) {
super(node);
this.properties = new Properties();
this.children = new Children();
this.references = new References();
}
public Properties getProperties() {
return this.properties;
}
public Children getChildren() {
return this.children;
}
public References getReferences() {
return this.references;
}
}

At the moment it's not possible to regenerate the API as part of the CI/gradle build, that's why the generated sources are checked into the repository. This limitation is specific this example and is somehow caused by the MPS build failing to load the right languages during the build. Other projects are successfully using the api-gen code generator within their CI/gradle build. The limitation will get fixed in the future but for now the generated Java code is checked into the repository.

The idea here is to illustrate read only use cases where a system/service outside of MPS wants to consume the content of models defined in MPS.

The dashboard is a simple application that contains a webserver that serves static HTML rendered from a model. A user can not edit that models from the browser. The imaginary use-case is a display next to the room that show the upcoming lectures in that room or a display in the main hall showing all the lectures of the current day.

The dashboard application is written in Kotlin and uses Ktor as a webserver, tailwind.css for styling and the generated API from the language. By default, the dashboard will try to load the models from an MPS instance running on your local machine. To get access to the models within your MPS it is using the mps-rest-model-access component from modelix.

Before running the actual dashboard you need to open the MPS project in the mps folder. This will set up MPS with the mps-rest-model-access plugin and expose your models via an HTTP API. This API is then accessed from the dashboard application to load the models.

Once your MPS project is opened you can run the dashboard:

./gradlew dashboard:run

Once you see a log message like:

11:12:41.672 [ktor-cio-dispatcher-worker-1] INFO ktor.application - Responding at http://0.0.0.0:8080

Your dashboard is ready you can point your browser to http://localhost:8080 to view the dashboard.

The Kotlin code for the dashboard features extensive code documentation that explains the various parts and how they are connected.

⚠️ TBD