CROM GLSP Diagram Editor

This project provides a diagram editor for Compartment Role Object Models (CROM), built using the Eclipse GLSP framework. It includes:

• 🖥️ A Java-based GLSP server for handling diagram-specific logic
• 🗂️ An EMF-based source model
• 🌐 A Theia integration to make your editor available as Theia application
• 🖼️ A VS Code extension for integrating the diagram editor into Visual Studio Code

The Compartment Role Object Model (CROM) is a conceptual modeling approach that enables dynamic assignment of roles to objects within specific contexts, called compartments. It supports flexible and context-dependent behavior by allowing objects to play different roles in different compartments, enhancing modularity and adaptability in software design. Building on these concepts, the Crom-GLSP leverages CROM principles to provide graphical modeling capabilities for compartment-role-based systems.

Project Structure

The project is organized as follows:

• server/: Java-based GLSP server implementation with EMF model handling
• client/: TypeScript/JavaScript client applications and extensions
  • browser-app/: Theia browser application
  • crom-theia/: Theia extension for CROM diagram editor
  • crom-vscode/: VS Code extension
  • packages/: Shared packages and components
  • workspace/: Example workspace with CROM files

Key Entry Points

• Server: server/src/main/java/../CromDiagramModule.java
• Client Base: client/packages/crom-sprotty/src/crom-diagram-module.ts
• Theia Browser App: client/browser-app/package.json
• VS Code Extension: client/crom-vscode/extension/src/crom-extension.ts

Prerequisites

Ensure the following are installed on your system:

• Node.js >=18
• Yarn >=1.7.0 <2
• Java >=17
• Maven >=3.6.0

This project is compatible with Theia >=1.39.0 and VS Code >=1.74.0.

Building the Project

The project consists of two main components that need to be built separately: the Java server and the TypeScript/JavaScript client applications.

Quick Build (All Components)

Use the provided build scripts to build both server and client:

Windows

.\build.ps1

Linux/macOS

./build.sh

Build specific components

You can also build individual components:

Java Server

.\build.ps1 server  # Windows

./build.sh server  # Linux/macOS

cd server
mvn clean verify

Client Applications

.\build.ps1 client  # Windows

./build.sh client  # Linux/macOS

cd client
yarn

cd client && yarn build:theia  # Build Theia application

cd client && yarn build:vscode  # Build VS Code extension

Clean Build Artifacts

To clean build artifacts, run:

.\build.ps1 clean  # Windows

./build.sh clean  # Linux/macOS

cd server && mvn clean  # Clean Java server artifacts

cd client && yarn clean  # Clean client artifacts

Running the Project

IntelliJ IDEA

The project includes IntelliJ IDEA configuration files in the .idea/ directory with pre-configured run configurations:

• Launch CROM GLSP Server: Starts the Java GLSP server on port 5007. Use this configuration for debugging server-side code.
• Theia (Launch CROM - Embedded GLSP Server): Launches Theia with embedded server. This configuration launches the Theia backend application and starts the GLSP server as an embedded process. Note that debugging the GLSP server source code is not possible in this mode.
• Theia (Launch CROM - External GLSP Server): Launches Theia connecting to external server. This configuration expects the GLSP server to be started externally using the Launch CROM GLSP Server configuration.

VS Code

Use the launch configurations defined in .vscode/launch.json. Open the project in Visual Studio Code and navigate to the Run and Debug view (Ctrl + Shift + D). Choose one of the following launch configurations:

• Launch CROM GLSP Server: Starts the standalone Java GLSP server. Use this configuration for debugging server-side code. Note: There is also a run configuration available for JetBrains-IDEs.

• Theia Configurations:

  • Backend with embedded GLSP server: This configuration launches the Theia backend application and starts the GLSP server as an embedded process. Breakpoints in the source files of the crom-theia/src/node directories will be picked up. Note: Debugging the GLSP server source code is not possible in this mode.
  • Backend with external GLSP server: This configuration launches the Theia backend application without embedding the GLSP server. Breakpoints in the source files of the crom-theia/src/node directories will be picked up. Note: This configuration expects the GLSP server to be started externally using the Launch CROM GLSP Server configuration.
  • Frontend Chrome launcher: Launches a Google Chrome instance and opens the Theia frontend at http://localhost:3000. The example workspace will automatically open, containing a .crom file. Double-click the file in the Explorer to open it with the CROM Diagram Editor. Breakpoints in the source files of the crom-theia/src/browser directories will be picked up.

• VS Code Extension Configurations:

  • Extension with embedded server: Starts a second VS Code instance with the extension installed. Opens an example workspace containing a .crom file. The GLSP server runs as an embedded process. Note: Server-side debugging is not available in this mode.
  • Extension with external server: Similar to the above, but expects the GLSP server to be started externally using the Launch CROM GLSP Server configuration. This allows debugging both the client and server code.

• Compound Configurations for launching multiple components simultaneously:

  • Theia: Launch CROM Theia Frontend & Backend with embedded GLSP Server: Launches both the Theia backend (with the embedded GLSP server) and the Theia frontend.
  • VS Code: Launch CROM extension with external GLSP Server: Launches both the CROM GLSP Server and the VS Code extension in external server mode. This enables simultaneous debugging of both the client and server code.

Packaging the VS Code Extension

To package the VS Code extension as a .vsix file, run:

cd client
yarn package

The resulting .vsix file will be located in the client-vscode/extension/dist directory and can be installed in VS Code.

Additional Documentation

More Documentation is available in separate location. This includes detailed information on architecture, design decisions, and usage examples

Resources

• Project GitLab Repository
• Eclipse GLSP
• Eclipse Modeling Framework
• Eclipse Theia