Skip to content

Prerequisites

In this chapter

  • install Java
  • get the example project
  • build the app, start backend and frontend, and open it in the browser
  • learn which command you need after which kind of change

Installation

Install Java 21

  • Download and install Java 21 and extract the folder. Older builds are in the Java archive.
  • The extracted folder contains jdk-21. You can copy it into Program Files/Java, the standard path for JDKs.
  • Add an environment variable JAVA_HOME with the jdk-21 directory as its value, e.g. C:\Program Files\Java\jdk-21.
  • Add the entry %JAVA_HOME%\bin to the Path environment variable.
  • Install a JDK 21 with your package manager:

    sudo apt install openjdk-21-jdk          # Debian, Ubuntu
    sudo dnf install java-21-openjdk-devel   # Fedora
    
  • Set JAVA_HOME in your ~/.bashrc. The path depends on the distribution, e.g. on Ubuntu:

    export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
    
  • Install a JDK 21 with Homebrew and register it with the system:

    brew install openjdk@21
    sudo ln -sfn $(brew --prefix)/opt/openjdk@21/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk-21.jdk
    
  • Set JAVA_HOME in your ~/.zshrc:

    export JAVA_HOME=$(/usr/libexec/java_home -v 21)
    

Open a new console and run java -version to check that Java works.

Tip

On Linux and macOS, SDKMAN! is an alternative: it installs a JDK and sets JAVA_HOME for you. sdk list java shows the available versions.

Access to the MontiGem artifacts

The MontiGem generator and its runtime are published in the Nexus repository of the Software Engineering chair. Gradle downloads them anonymously, so you need neither an account nor any configuration for this tutorial.

(Optional) Install a plugin for language support

The plugins add syntax highlighting and code completion for the modeling languages.

Downloads

Plugin installation guides

Getting the project

Download the training version of the example project: montigem3-training.zip. Unpack it anywhere.

In the training version, every place where you add code is marked with a // TODO: comment that names the chapter, for example:

models/Carrental.umlp
  // TODO: 01 Class Diagram Basics - enum RentableStatus

Alternative for Windows: the launcher

The experimental launcher installs the same training version and sets up Java and Gradle for you. Download the launcher, start it and choose the project type montigem_tutorial.

Commands

Run all commands in a console in the project folder. In the Windows command prompt (cmd) write gradlew instead of ./gradlew.

Build

To build the project, use the following command:

./gradlew build

Note

The first build takes 10 to 20 minutes and has long phases without any output. npm warn messages are normal.

Run

Backend and frontend run as two separate processes. Neither of them stops on its own, so use two console windows.

Open a console and start the backend:

./gradlew :backend:run

The backend is ready when the log ends with these two lines:

[restartedMain] INFO org.springframework.boot.web.embedded.tomcat.TomcatWebServer - Tomcat started on port 8081 (http) with context path '/umlp/api'
[restartedMain] INFO carrental.CarrentalServerApplication - Started CarrentalServerApplication in 3.2 seconds (process running for 3.6)

Note

Yellow [WARN] lines before them, such as I AM ALIVE!, are normal start-up output.

Open another console and start the frontend:

./gradlew :frontend:run

The frontend is ready when the last lines are:

Application bundle generation complete.
Watch mode enabled. Watching for file changes...
    Local:   http://localhost:4200/

Note

Yellow Deprecation [plugin angular-sass] warnings are harmless.

Open the browser and navigate to localhost:4200 to see the app. The app shows a text directing you to the start of the tutorial:

first tutorial app page

Stop

Stop the backend or the frontend by pressing ctrl+c in its console.

Warning

The next instruction kills the process that uses port 4200. This is the node process running the frontend app. If you have a special setup that uses port 4200 for something else you will need to adjust the scripts.

The frontend dev server sometimes survives ctrl+c, because Gradle starts it as a separate process. Run the killfe script in the project folder in a console with administrative rights:

killfe

On Windows you can also use killfe.ps1 in a PowerShell. For a Unix-like environment use:

sudo ./killfe.sh

Note

killfe stands for kill frontend. The script finds the process which uses port 4200 and kills it if such a process is found. This is a crutch of the gradle build system and OS process management. The behavior may vary and you might not need to kill the process manually, it might terminate on its own later.

Which command after which change

While backend and frontend are running, you do not rebuild everything. Use this table. Every chapter repeats the command you need at that point.

You changed Run this
A GUI model (*.gui), frontend Java, SCSS or a new hand-written TypeScript file ./gradlew :frontend:generate
The class diagram models/Carrental.umlp restart the backend, then ./gradlew :frontend:generate
A new file in models/ocl/ ./gradlew :backend:umlp2java --rerun-tasks, restart the backend, then ./gradlew :frontend:generate
Backend Java code only restart the backend
An existing hand-written TypeScript file in frontend/src/main/gui nothing, the dev server picks it up

Run ./gradlew :frontend:generate in a third console while ./gradlew :frontend:run keeps running.

When the dev server has picked up the change, the console that runs ./gradlew :frontend:run prints:

Application bundle generation complete.
Page reload sent to client(s).

Let Gradle watch your files

Instead of running generate after every change, you can start ./gradlew :frontend:continuous --continuous in the third console. Gradle then waits for changes and runs generate whenever you save one of its inputs: a GUI model, frontend code or the class diagram. Stop it with ctrl+c. After a change of the class diagram you still restart the backend yourself.

Try it

Open frontend/src/main/gui/gui/Start.gui. It shows a text and a link:

frontend/src/main/gui/gui/Start.gui
page Start() {
  @GemText(value = "This is a tutorial application for developers learning to create a MontiGem app.");
  @GemLink(
    url = "https://monticore.pages.rwth-aachen.de/umlp/Tutorial.html",
    text = "Visit the tutorial page to learn how to build a MontiGem app."
  );
}

Change the value of the @GemText to "Hello, World!" and run:

./gradlew :frontend:generate

The first run of this command takes a bit. When it is done, the browser reloads and shows your text.

Note

If your changes are invalid, e.g. the updated GUI model has errors, the console running ./gradlew :frontend:generate displays the error and the page does not reload. Fix the error and run the command again.

If something does not work

Symptom Cause and fix
The backend stops right after start, or the frontend cannot reach it (the log says Port 8081 was already in use) Port 8081 is already in use, for example by another MontiGem app. Stop that app. If you cannot, start the backend on another port and tell the frontend about it: set PORT=8082 before :backend:run and BACKEND_PROXY_ADDRESS=http://localhost:8082/ before :frontend:run. In PowerShell that is $env:PORT="8082" and $env:BACKEND_PROXY_ADDRESS="http://localhost:8082/", each in the console of the process it belongs to.
Port 4200 is already in use An old dev server is still running. Use killfe.
[vite] ws proxy error: ECONNREFUSED in the frontend console The backend is not running (yet). Start it, and the message disappears.
TS2307: Cannot find module 'carrental/...' after a model change The frontend has the new GUI code but not the new domain code. Run ./gradlew :frontend:generate.
The console of generate prints Failed to open non-existing directory: ...\cd2java or ...\ocl2java Normal. MontiGem creates these folders only when the project uses the matching generator, ocl2java for example from chapter 12 on.
Compile errors in files under build/ Those files are generated. The cause is in your model or in your hand-written code. Fix that and generate again.
A JSweet error mentioning getLineMap() Your frontend Java code does not compile. Fix the Java error first. The JSweet message is only a consequence of it.
Authentication error (401) while downloading dependencies Outdated mavenUser and mavenPassword entries in %userprofile%/.gradle/gradle.properties are sent to Nexus and rejected. Correct or remove them, the tutorial does not need them.

Checkpoint

  • ./gradlew build finishes with BUILD SUCCESSFUL.
  • The backend log ends with Started CarrentalServerApplication in ... seconds.
  • localhost:4200 shows the start page with the text and the link, as in the screenshot above.
  • After changing the @GemText and running ./gradlew :frontend:generate, the browser shows the new text.