Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Methodologist Setup Service

A Spring Boot REST API service for the Vitruv methodologist workflow. It validates and standardizes GenModel files for MWE2 compatibility, and builds VSUMs from uploaded metamodels, reactions, constraints, and view definitions.

Features

  • GenModel Validation: Inspect GenModel files for compliance issues without modifying them
  • GenModel Processing: Apply standardization rules and download the corrected file
  • VSUM Build: Generate genmodels and a Methodologist-Template project from metamodels, reactions, VitruvOCL constraints, and NeoJoin view definitions, build and smoke-test it, and return the project zip or executable jar
  • VSUM Validation: Run the checks of the build without building, e.g. after every save
  • OpenAPI / Swagger UI: Interactive API documentation
  • Error Handling: Centralized exception handling with structured error responses
  • Docker Support: Dockerfile and Compose setup included

Quick Start

Prerequisites

  • Java 21+
  • Maven 3.8+ (or the bundled ./mvnw wrapper)
  • Docker (optional)

Build

./mvnw clean package

Run Locally

java -jar target/methodologist-setup-service-1.0.1.jar

The service starts on http://localhost:8090.

Run with Docker

docker compose up --build

The image builds the service itself and then builds a sample VSUM project once, which fills the image's Maven repository (/opt/vsum-m2) with every dependency of the generated projects. In the container, VSUM builds run offline: they do not depend on Maven Central, and the first build after a deployment is as fast as the others. Building the image needs network access.

To change the Vitruvius, VitruvOCL, NeoJoin, EMF, or plugin versions, change them in VsumBuildProperties and rebuild the image. A version overridden at runtime (SETUP_VSUM_*_VERSION) that is missing from the image is downloaded once and logged (setup.vsum.online-fallback); set SETUP_VSUM_ONLINE_FALLBACK=false to fail instead.

On startup, the container builds the sample project again, offline. Until that succeeds, /actuator/health/readiness reports OUT_OF_SERVICE, so a deployment with a broken repository or incompatible versions never receives traffic.

API Endpoints

Interactive docs: http://localhost:8090/swagger-ui.html — OpenAPI spec: http://localhost:8090/api-docs

Inspect GenModel

POST /api/genmodel/inspect (multipart/form-data)

Analyzes a GenModel file and previews what changes would be applied. Returns JSON.

curl -X POST -F "file=@mymodel.genmodel" http://localhost:8090/api/genmodel/inspect

Response:

{
  "data": [
    {
      "filename": "mymodel.genmodel",
      "message": "Would remove attributes: complianceLevel"
    }
  ],
  "message": "GenModel inspected successfully, showing planned changes"
}

Process GenModel

POST /api/genmodel/process (multipart/form-data)

Applies the standardization rules and returns the processed file itself as a download (application/octet-stream), not a JSON summary.

curl -X POST -F "file=@mymodel.genmodel" \
  -o mymodel.processed.genmodel \
  http://localhost:8090/api/genmodel/process

Build VSUM

POST /api/vsum/build returns the generated project as a zip; POST /api/vsum/jar returns the executable VSUM jar, which hosts the VSUM in a Vitruvius server (java -jar <jar> [port], type quit to stop).

Part Required Content
metamodelFiles yes Ecore metamodels (.ecore)
reactionFiles no Reactions consistency specifications (.reactions)
constraintFiles no VitruvOCL constraints (.ocl)
viewFiles no NeoJoin view definitions (.nj), each becomes a view type
curl -X POST \
  -F metamodelFiles=@model.ecore -F metamodelFiles=@model2.ecore \
  -F reactionFiles=@templateReactions.reactions \
  -F constraintFiles=@constraints.ocl \
  -F viewFiles=@components.nj \
  -o vsum.jar http://localhost:8090/api/vsum/jar

Genmodels are not uploaded; they are generated from the metamodels. The pipeline:

  1. Validates the uploads (non-empty, expected extension, unique names).
  2. Loads the metamodels, resolves references between them (relative, platform:/resource, or nsURI), validates them with EMF, rejects names whose generated Java code does not compile, and generates matching genmodels.
  3. Checks the reactions against the loaded metamodels: every import refers to an uploaded nsURI, and aliases, classes, and trigger features exist and fit (see Checks before the build).
  4. Checks the view definitions with NeoJoin against the loaded metamodels (syntax, imports, types, unique exports and nsURIs), and that the view type names derived from the file names are unique and do not clash with the metamodels.
  5. Generates a project following the Methodologist Template (model, consistency, vsum, and viewtype if there are view definitions), with a smoke test that creates and reloads the VSUM, compiles the constraints, and creates a view of every NeoJoin view type.
  6. Runs mvn clean verify.

The generated VSUM registers the VitruvOCL constraints at the virtual model, so its Vitruv server lists, validates, and manages them under /vsum/constraints, and validates them after every change propagation.

Each view definition becomes a view type, generated by NeoJoin for Vitruvius and named after the file (components.nj → Components; _, -, and spaces are removed and the following letter is upper case). The Vitruv server lists it next to the view types of the metamodels under /vsum/view/types and creates views of it under /vsum/view. Changes in these views are propagated back to the models where NeoJoin can invert the query, e.g. for plain attribute projections.

Invalid inputs are rejected with 400 before Maven runs (VSUM_INPUT_ERROR, VSUM_METAMODEL_ERROR, VSUM_REACTIONS_ERROR, VSUM_VIEWS_ERROR). Failed Maven builds are classified by their output, so that only problems of the uploads are reported as such:

Status Error code Cause
422 VSUM_BUILD_FAILED The uploaded metamodels, reactions, constraints, or views do not compile, or the smoke test fails
503 VSUM_BUILD_UNAVAILABLE The build environment failed (dependency download, disk space, memory); retried once first
500 VSUM_INTERNAL_ERROR Code the service generates itself does not build, or the library versions are incompatible
504 VSUM_BUILD_TIMEOUT The build exceeded setup.vsum.build-timeout; the message names the module being built

Errors of the uploads are attributed to the file that causes them, with the line of the upload, an excerpt, and a hint where one is known. They are listed in problems, root causes first; message contains the same as readable text:

{
  "errorCode": "VSUM_REACTIONS_ERROR",
  "status": 400,
  "message": "The uploaded reactions do not match the uploaded metamodels:\n\nmy.reactions:\n- line 51, column 30: ...",
  "problems": [
    {
      "source": "REACTIONS",
      "file": "my.reactions",
      "line": 51,
      "column": 30,
      "message": "'Entitiy' is not a class of the metamodel 'model2' (http://vitruv.tools/methodologisttemplate/model2)",
      "excerpt": "    val entity = new model2::Entitiy\n                             ^",
      "hint": "Did you mean 'Entity'?"
    }
  ]
}

source is METAMODEL, REACTIONS, CONSTRAINTS, VIEWS, INFRASTRUCTURE, or INTERNAL; file, line, column, excerpt, hint, and hiddenFollowUpErrors are omitted when unknown. Errors that only follow from another one, e.g. everything after a syntax error in the same reactions file, are not listed but counted in hiddenFollowUpErrors. Problems are reported for metamodels and reactions rejected before the build, for view definitions rejected before the build, for Reactions, NeoJoin, and Java compiler errors, and for failures of the smoke test (constraints that cannot be evaluated, exceptions in reactions or routines while creating the VSUM, view types that cannot be created).

Validate VSUM

POST /api/vsum/validate takes the same parts as /api/vsum/build and runs the checks before the build through the same code, without writing a project or running Maven, so it can run after every save while the project is edited.

It returns 200 also for invalid projects, with the problems the build would report before Maven:

{
  "valid": false,
  "problems": [
    {
      "source": "REACTIONS",
      "file": "my.reactions",
      "line": 51,
      "column": 30,
      "message": "'Entitiy' is not a class of the metamodel 'model2' (http://vitruv.tools/methodologisttemplate/model2)",
      "excerpt": "    val entity = new model2::Entitiy\n                             ^",
      "hint": "Did you mean 'Entity'?"
    }
  ]
}

valid is false if there is any problem. Like the build, the checks stop at the first stage with problems: reactions are only checked once the metamodels are valid. Malformed requests (no metamodel, empty files, wrong extensions, duplicate names) are rejected with 400 and VSUM_INPUT_ERROR or INVALID_REQUEST, as for builds. Errors only Maven finds (Reactions compiler, Java compiler, smoke test) are not reported. Validations don't use the build slots (setup.vsum.max-concurrent-builds), so they never wait for running builds.

Checks before the build

Most mistakes are found in milliseconds, before Maven runs, and come with a suggestion:

  • Metamodels: EMF validation, with messages naming the element (Thing.untyped) and a hint; names that differ only in upper/lower case or _ (classes, features including inherited ones, enum literals), Java reserved words as class names (class, record, var), and classes named like the generated <Package>Package/<Package>Factory interfaces. EMF escapes reserved words in feature, literal, and package names, so these are accepted.
  • Reactions: aliases in segment headers and before ::, alias::Class (including subpackages and using qualified names), [feature] in triggers (attribute for after attribute, reference for after element, single-valued for replaced at, many-valued for inserted in/removed from, and an element type that fits the reference), and abstract classes, interfaces, or enums in create blocks.

Errors only the Reactions compiler finds (syntax, Xbase expressions) are reported after the build, with a hint from a catalog of compiler messages (CompilerHints).

Dependency on the Reactions language

The reactions checks (ReactionsChecker) do not use the Reactions language (tools.vitruv.dsls.reactions.language); they reimplement the rules of its grammar (ReactionsLanguage.xtext), scope provider (CommonLanguageElementsScopeProvider, ReactionsLanguageScopeProvider), and validator (ReactionsLanguageValidator) in Vitruv-DSLs, as of version 4.0.0. When setup.vsum.vitruv-dsls-version is raised, compare these files with the version the checks follow and adapt ReactionsChecker and CompilerHints. The checks only report what is certainly wrong and leave everything else to the compiler, so a newer language can at worst make them miss a mistake; a failure of the checker itself is logged and leaves the decision to the compiler.

The language is deliberately not a dependency of the service: it brings Xtext/Xbase, Guice, ANTLR 3, log4j-core, and Eclipse p2 wrappers, which conflict with Spring Boot's logging and dependency versions. Linking Xbase expressions also needs the Java classes generated from the metamodels, which exist only after the Maven build. Parsing with the real grammar before the build would therefore run in a separate JVM on the jars the warm-up build puts into the Maven repository of the image.

The workspaces of 503 and 500 builds are kept in the temporary directory for debugging and deleted on a later startup once older than setup.vsum.workspace-retention.

Build settings are configured with setup.vsum.* properties (see VsumBuildProperties), e.g. setup.vsum.build-timeout, setup.vsum.max-concurrent-builds, setup.vsum.maven-arguments, setup.vsum.maven-repository, setup.vsum.offline, setup.vsum.maven-opts (the builds' JVM options; the service's JAVA_TOOL_OPTIONS are not passed on), the Vitruvius/VitruvOCL/NeoJoin versions, and setup.vsum.keep-failed-workspaces for debugging. Concurrent builds share the local repository with file locking (Maven 3.9+).

Standardization Rules

The GenModel endpoints apply these normalization rules:

  1. Removes deprecated attributes:

    • complianceLevel, compliance, editDirectory, editorDirectory, etc.
  2. Ensures correct basePackage:

    • Sets basePackage to match modelPluginID for all GenPackages
  3. Standardizes modelDirectory:

    • Format: /{modelPluginID}/target/generated-sources/ecore
  4. Enforces creationIcons:

    • Sets to false
  5. Ensures foreignModel reference:

    • Adds missing foreignModel entry automatically

Project Structure

src/main/java/tools/vitruv/methodologist/setup/
├── model/
│   ├── controller/           # GenModel REST controller + DTOs
│   └── service/              # GenModel precheck, file, and ecore-to-genmodel services
├── vsum/
│   ├── controller/           # VSUM REST controller
│   └── service/              # VSUM build pipeline (metamodel, reactions, constraints, views,
│                             # project generation, Maven build)
├── config/                   # Swagger, exception handling
├── exception/                # Custom exceptions and error DTOs
├── log/                      # Request/response logging filter
├── messages/                 # Error and info message constants
├── ResponseTemplateDto.java  # Generic API response envelope
└── MethodologistSetupServiceApplication.java

src/main/resources/templates/vsum/ # FreeMarker templates for generated VSUM projects

Health Check

curl http://localhost:8090/actuator/health
curl http://localhost:8090/actuator/health/liveness
curl http://localhost:8090/actuator/health/readiness   # includes the VSUM build warm-up

Configuration

See src/main/resources/application.properties.

Default settings:

  • Port: 8090
  • Application name: methodologist-setup-service
  • Swagger UI: /swagger-ui.html
  • OpenAPI docs: /api-docs
  • Log level for tools.vitruv.methodologist: DEBUG

Technologies

  • Framework: Spring Boot 4.0.6
  • Modeling: Eclipse EMF (Ecore 2.43.0, XMI 2.41.0, Codegen 2.47.0)
  • Templating: FreeMarker
  • API Docs: springdoc-openapi 3.0.0
  • Logging: Logback with logstash JSON encoder
  • Build Tool: Maven (Spotless, Checkstyle, Surefire)
  • Java Version: 21 LTS

Development

./mvnw clean verify        # full build with tests
./mvnw verify -Dvsum.integration=true   # also builds generated VSUM projects with Maven
./mvnw spotless:apply      # auto-format sources
./mvnw checkstyle:check    # style check against checkstyle.xml

CI (.github/workflows/ci.yml) runs mvnw clean verify on PRs to main and develop, builds generated VSUM projects with Maven, builds the Docker image and checks that it builds VSUMs offline, plus nightly SonarQube analysis and a Checkstyle review pass.

Error Handling

All requests return appropriate HTTP status codes:

  • 200 OK: Successful operation
  • 400 Bad Request: Invalid input or processing error
  • 413 Content Too Large: Uploads exceed the configured size limit
  • 422 Unprocessable Content: Invalid GenModel, or the generated VSUM does not build
  • 500 Internal Server Error: Unexpected server error, or the generated VSUM project fails for reasons of the service itself (VSUM_INTERNAL_ERROR)
  • 503 Service Unavailable: The VSUM build environment failed; retrying later may succeed
  • 504 Gateway Timeout: The VSUM build exceeded its timeout

Errors are handled centrally in GlobalExceptionHandler and returned as structured responses with a message and error code to help with debugging.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages