Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,11 @@ RUN mvn --batch-mode --no-transfer-progress -DskipTests package \
FROM ${MAVEN_IMAGE}
COPY --from=build /workspace/app.jar /app/app.jar

# Fill the Maven repository of the VSUM builds by building a sample project once. The image then
# contains every dependency of the generated projects, and builds run offline: they do not depend
# on Maven Central being reachable, and the first build after a deployment is as fast as the rest.
# Fill the Maven repository of the VSUM builds by building a sample project once. The sample has
# every kind of input (metamodels, reactions, VitruvOCL constraints, a NeoJoin view), so the image
# then contains every dependency of the generated projects, including the NeoJoin compiler, and
# builds run offline: they do not depend on Maven Central being reachable, and the first build
# after a deployment is as fast as the rest.
# To change versions (setup.vsum.*-version), rebuild the image.
ENV SETUP_VSUM_MAVEN_REPOSITORY=/opt/vsum-m2
RUN java -jar /app/app.jar \
Expand Down
35 changes: 24 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,8 @@ constraints, and view definitions.
- **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,
and VitruvOCL constraints, build and smoke-test it, and return the project zip or executable jar
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
Expand Down Expand Up @@ -48,7 +49,7 @@ Maven repository (`/opt/vsum-m2`) with every dependency of the generated project
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, EMF, or plugin versions, change them in `VsumBuildProperties` and
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.
Expand Down Expand Up @@ -108,13 +109,14 @@ executable VSUM jar, which hosts the VSUM in a Vitruvius server (`java -jar <jar
| `metamodelFiles` | yes | Ecore metamodels (`.ecore`) |
| `reactionFiles` | no | Reactions consistency specifications (`.reactions`) |
| `constraintFiles` | no | VitruvOCL constraints (`.ocl`) |
| `viewFiles` | no | NeoJoin view definitions (stored in the project, not compiled yet) |
| `viewFiles` | no | NeoJoin view definitions (`.nj`), each becomes a view type |

```bash
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
```

Expand All @@ -126,20 +128,30 @@ Genmodels are not uploaded; they are generated from the metamodels. The pipeline
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](#checks-before-the-build)).
4. Generates a project following the [Methodologist Template](https://github.com/vitruv-tools/Methodologist-Template)
(`model`, `consistency`, `vsum`), with a smoke test that creates and reloads the VSUM and compiles the constraints.
5. Runs `mvn clean verify`.
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](https://github.com/vitruv-tools/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](https://github.com/vitruv-tools/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`). Failed Maven builds are classified by their output, so that only problems of the
`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, or constraints do not compile, or the smoke test fails |
| `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 |
Expand Down Expand Up @@ -171,8 +183,9 @@ contains the same as readable text:
`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 Reactions compiler 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).
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

Expand Down Expand Up @@ -247,7 +260,7 @@ 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 versions, and
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+).

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,8 @@ public ResponseEntity<byte[]> buildProject(
@Parameter(description = "VitruvOCL constraint files")
@RequestPart(value = "constraintFiles", required = false)
List<MultipartFile> constraintFiles,
@Parameter(description = "NeoJoin view definitions (stored, not yet compiled)")
@Parameter(
description = "NeoJoin view definitions (.nj); each becomes a view type of the VSUM")
@RequestPart(value = "viewFiles", required = false)
List<MultipartFile> viewFiles) {
VsumBuildRequest request =
Expand Down Expand Up @@ -113,7 +114,8 @@ public ResponseEntity<byte[]> buildJar(
@Parameter(description = "VitruvOCL constraint files")
@RequestPart(value = "constraintFiles", required = false)
List<MultipartFile> constraintFiles,
@Parameter(description = "NeoJoin view definitions (stored, not yet compiled)")
@Parameter(
description = "NeoJoin view definitions (.nj); each becomes a view type of the VSUM")
@RequestPart(value = "viewFiles", required = false)
List<MultipartFile> viewFiles) {
VsumBuildRequest request =
Expand Down Expand Up @@ -159,7 +161,8 @@ public VsumValidationResult validateProject(
@Parameter(description = "VitruvOCL constraint files")
@RequestPart(value = "constraintFiles", required = false)
List<MultipartFile> constraintFiles,
@Parameter(description = "NeoJoin view definitions")
@Parameter(
description = "NeoJoin view definitions (.nj); each becomes a view type of the VSUM")
@RequestPart(value = "viewFiles", required = false)
List<MultipartFile> viewFiles) {
VsumBuildRequest request =
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -98,6 +98,14 @@ public class VsumBuildProperties {
*/
private String vitruvoclVersion = "0.1.0-SNAPSHOT";

/**
* Version of NeoJoin for Vitruvius ({@code tools.vitruv:tools.vitruv.neojoin.vitruv.*}), which
* generates the view types of the view definitions. It has no release yet; pin a timestamped
* snapshot once one is published, so that builds do not change whenever a new snapshot is
* published.
*/
private String neojoinVitruvVersion = "0.1.0-SNAPSHOT";

/** Version of {@code org.eclipse.emf.common}. */
private String emfCommonVersion = "2.46.0";

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ public record VsumBuildRequest(
/** File extension of VitruvOCL constraint files. */
public static final String CONSTRAINTS_EXTENSION = ".ocl";

/** File extension of view files. */
/** File extension of NeoJoin view definitions. */
public static final String VIEWS_EXTENSION = ".nj";

/** Makes the lists immutable and rejects {@code null} lists. */
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -90,7 +90,8 @@ boolean warmUp() {

/**
* The sample project: the two metamodels, reactions, and constraints of the Methodologist
* Template, which together need every dependency a generated project can have.
* Template and a NeoJoin view definition, which together need every dependency a generated
* project can have.
*
* @return the build request of the sample project
*/
Expand All @@ -99,7 +100,7 @@ static VsumBuildRequest sampleRequest() {
List.of(sample("model.ecore"), sample("model2.ecore")),
List.of(sample("templateReactions.reactions")),
List.of(sample("constraints.ocl")),
List.of());
List.of(sample("components.nj")));
}

private static UploadedFile sample(String name) {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,12 @@ public final class VsumErrorCodes {
/** An uploaded reactions file does not fit the uploaded metamodels. */
public static final String REACTIONS_ERROR = "VSUM_REACTIONS_ERROR";

/** An uploaded view definition is invalid or does not fit the uploaded metamodels. */
public static final String VIEWS_ERROR = "VSUM_VIEWS_ERROR";

/**
* The Maven build rejected the uploaded files: the metamodels, reactions, or constraints do not
* compile, or the smoke test failed.
* The Maven build rejected the uploaded files: the metamodels, reactions, constraints, or views
* do not compile, or the smoke test failed.
*/
public static final String BUILD_FAILED = "VSUM_BUILD_FAILED";

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@
import tools.vitruv.methodologist.setup.vsum.service.project.ProjectGenerator;
import tools.vitruv.methodologist.setup.vsum.service.project.ProjectLayout;
import tools.vitruv.methodologist.setup.vsum.service.reactions.ReactionsProcessor;
import tools.vitruv.methodologist.setup.vsum.service.views.GeneratedViewType;
import tools.vitruv.methodologist.setup.vsum.service.views.NeoJoinChecker;
import tools.vitruv.methodologist.setup.vsum.service.views.ViewDefinitionProcessor;

Expand Down Expand Up @@ -133,16 +134,20 @@ ProjectSources generateProject(VsumBuildRequest request, Path projectRoot) throw
reactionsProcessor.process(request.reactions(), metamodels, projectRoot);
List<String> constraintResources =
constraintsProcessor.process(request.constraints(), projectRoot);
// NeoJoin parses and validates the views; the processor then derives the generated names
neoJoinChecker.check(request.viewDefinitions(), metamodels);
viewDefinitionProcessor.process(request.viewDefinitions(), metamodels, projectRoot);
projectGenerator.generate(projectRoot, metamodels, specifications, constraintResources);
return sources(request, metamodels, constraintResources, projectRoot);
List<GeneratedViewType> viewTypes =
viewDefinitionProcessor.process(request.viewDefinitions(), metamodels, projectRoot);
projectGenerator.generate(
projectRoot, metamodels, specifications, constraintResources, viewTypes);
return sources(request, metamodels, constraintResources, viewTypes, projectRoot);
}

private static ProjectSources sources(
VsumBuildRequest request,
List<GeneratedMetamodel> metamodels,
List<String> constraintResources,
List<GeneratedViewType> viewTypes,
Path projectRoot) {
ProjectSources sources = new ProjectSources(projectRoot);
// the metamodel processor returns one entry per upload, in upload order
Expand Down Expand Up @@ -181,12 +186,16 @@ private static ProjectSources sources(
null);
sources.addConstraintResource(constraintResources.get(i), file);
}
for (UploadedFile view : request.viewDefinitions()) {
sources.add(
Source.VIEWS,
ProjectLayout.viewsDirectory(projectRoot).resolve(view.fileName()),
view,
null);
// the view definition processor returns one entry per upload, in upload order
for (int i = 0; i < viewTypes.size() && i < request.viewDefinitions().size(); i++) {
UploadedFile view = request.viewDefinitions().get(i);
SourceFile file =
sources.add(
Source.VIEWS,
ProjectLayout.viewsDirectory(projectRoot).resolve(view.fileName()),
view,
null);
sources.addView(viewTypes.get(i).exportName(), viewTypes.get(i).name(), file);
}
return sources;
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@
import tools.vitruv.methodologist.setup.vsum.service.problem.VsumBuildException;
import tools.vitruv.methodologist.setup.vsum.service.reactions.ReactionsProcessor;
import tools.vitruv.methodologist.setup.vsum.service.views.NeoJoinChecker;
import tools.vitruv.methodologist.setup.vsum.service.views.ViewDefinitionProcessor;

/**
* Checks a VSUM project without building it, so that problems can be shown while it is edited.
Expand All @@ -28,6 +29,7 @@ public class VsumValidationService {
private final MetamodelProcessor metamodelProcessor;
private final ReactionsProcessor reactionsProcessor;
private final NeoJoinChecker neoJoinChecker;
private final ViewDefinitionProcessor viewDefinitionProcessor;

/**
* Checks the project. Like the build, the checks stop at the first stage with problems: reactions
Expand All @@ -42,6 +44,7 @@ public VsumValidationResult validate(VsumBuildRequest request) {
List<GeneratedMetamodel> metamodels = metamodelProcessor.check(request.metamodels());
reactionsProcessor.check(request.reactions(), metamodels);
neoJoinChecker.check(request.viewDefinitions(), metamodels);
viewDefinitionProcessor.check(request.viewDefinitions(), metamodels);
return VsumValidationResult.of(List.of());
} catch (VsumBuildException e) {
log.debug("VSUM validation found problems: {}", e.getMessage());
Expand Down
Loading
Loading