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
33 changes: 33 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ constraints, and view definitions.
- **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
- **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
Expand Down Expand Up @@ -173,6 +174,38 @@ but counted in `hiddenFollowUpErrors`. Problems are reported for metamodels and
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).

### Validate VSUM

**POST** `/api/vsum/validate` takes the same parts as `/api/vsum/build` and runs the
[checks before the build](#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:

```json
{
"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:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -21,16 +21,19 @@
import org.springframework.web.multipart.MultipartFile;
import tools.vitruv.methodologist.setup.vsum.service.VsumBuildRequest;
import tools.vitruv.methodologist.setup.vsum.service.VsumProjectBuildService;
import tools.vitruv.methodologist.setup.vsum.service.VsumValidationResult;
import tools.vitruv.methodologist.setup.vsum.service.VsumValidationService;
import tools.vitruv.methodologist.setup.vsum.service.project.ProjectLayout;

/** REST API for VSUM project generation and packaging. */
/** REST API for VSUM project generation, packaging, and validation. */
@RestController
@RequestMapping("/api/vsum")
@RequiredArgsConstructor
@Tag(name = "VSUM", description = "VSUM project generation endpoints")
public class VsumController {

private final VsumProjectBuildService vsumProjectBuildService;
private final VsumValidationService vsumValidationService;

/**
* Builds a VSUM from the uploaded files and returns the generated project as a zip archive.
Expand Down Expand Up @@ -119,6 +122,51 @@ public ResponseEntity<byte[]> buildJar(
return attachment(jar, "application/java-archive", ProjectLayout.VSUM_JAR_FILENAME);
}

/**
* Checks the uploaded files like a build does before Maven runs, without building them.
*
* @param metamodelFiles Ecore metamodels
* @param reactionFiles Reactions consistency specifications
* @param constraintFiles VitruvOCL constraints
* @param viewFiles NeoJoin view definitions
* @return whether the project is valid, and its problems
*/
@PostMapping(
value = "/validate",
consumes = MediaType.MULTIPART_FORM_DATA_VALUE,
produces = MediaType.APPLICATION_JSON_VALUE)
@Operation(
summary = "Validate VSUM project",
description =
"Runs the checks /build runs before Maven, without generating a project or running"
+ " Maven, and returns the problems found. Invalid projects are reported with 200"
+ " and valid: false. Validations do not use the build slots, so they never wait"
+ " for running builds",
responses = {
@ApiResponse(
responseCode = "200",
description = "Validation result, also for invalid projects",
content = @Content(mediaType = "application/json")),
@ApiResponse(responseCode = "400", description = "Malformed request")
})
public VsumValidationResult validateProject(
@Parameter(description = "Ecore metamodel files", required = true)
@RequestPart("metamodelFiles")
List<MultipartFile> metamodelFiles,
@Parameter(description = "Reactions files")
@RequestPart(value = "reactionFiles", required = false)
List<MultipartFile> reactionFiles,
@Parameter(description = "VitruvOCL constraint files")
@RequestPart(value = "constraintFiles", required = false)
List<MultipartFile> constraintFiles,
@Parameter(description = "NeoJoin view definitions")
@RequestPart(value = "viewFiles", required = false)
List<MultipartFile> viewFiles) {
VsumBuildRequest request =
VsumBuildRequest.fromMultipart(metamodelFiles, reactionFiles, constraintFiles, viewFiles);
return vsumValidationService.validate(request);
}

private ResponseEntity<byte[]> attachment(byte[] content, String mediaType, String filename) {
HttpHeaders headers = new HttpHeaders();
headers.setContentType(MediaType.parseMediaType(mediaType));
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -124,6 +124,7 @@ private static boolean isNotCausedByTheUploads(MethodologistSetupException e) {
* @throws IOException when writing the project fails
*/
ProjectSources generateProject(VsumBuildRequest request, Path projectRoot) throws IOException {
// VsumValidationService runs the checks of these steps without writing; keep both in sync
List<GeneratedMetamodel> metamodels =
metamodelProcessor.process(request.metamodels(), projectRoot);
List<String> specifications =
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
package tools.vitruv.methodologist.setup.vsum.service;

import java.util.List;
import tools.vitruv.methodologist.setup.vsum.service.problem.BuildProblem;

/**
* The result of checking a VSUM project without building it.
*
* @param valid whether the build would get past its checks, i.e. there is no error
* @param problems the problems the build would report before running Maven, root causes first
*/
public record VsumValidationResult(boolean valid, List<BuildProblem> problems) {

/** Makes the problem list immutable. */
public VsumValidationResult {
problems = List.copyOf(problems);
}

/**
* Creates the result for the problems of the checks; the project is valid if there are none.
*
* @param problems the problems, empty if the checks passed
* @return the result
*/
public static VsumValidationResult of(List<BuildProblem> problems) {
return new VsumValidationResult(problems.isEmpty(), problems);
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
package tools.vitruv.methodologist.setup.vsum.service;

import java.util.List;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;
import tools.vitruv.methodologist.setup.vsum.service.metamodel.GeneratedMetamodel;
import tools.vitruv.methodologist.setup.vsum.service.metamodel.MetamodelProcessor;
import tools.vitruv.methodologist.setup.vsum.service.problem.VsumBuildException;
import tools.vitruv.methodologist.setup.vsum.service.reactions.ReactionsProcessor;

/**
* Checks a VSUM project without building it, so that problems can be shown while it is edited.
*
* <p>Runs the checks {@link VsumProjectBuildService} runs before Maven, through the same code, but
* writes no project and does not run Maven. Validations do not use the build slots ({@code
* setup.vsum.max-concurrent-builds}), so they never wait behind running builds.
*/
@Slf4j
@Service
@RequiredArgsConstructor
public class VsumValidationService {

private final MetamodelProcessor metamodelProcessor;
private final ReactionsProcessor reactionsProcessor;

/**
* Checks the project. Like the build, the checks stop at the first stage with problems: reactions
* are only checked once the metamodels are valid.
*
* @param request the project, as for a build
* @return the problems the build would report before running Maven
*/
public VsumValidationResult validate(VsumBuildRequest request) {
try {
List<GeneratedMetamodel> metamodels = metamodelProcessor.check(request.metamodels());
reactionsProcessor.check(request.reactions(), metamodels);
return VsumValidationResult.of(List.of());
} catch (VsumBuildException e) {
log.debug("VSUM validation found problems: {}", e.getMessage());
return VsumValidationResult.of(e.getProblems());
}
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,12 @@ public class MetamodelProcessor {
private static final Map<String, Object> SAVE_OPTIONS =
Map.of(XMLResource.OPTION_ENCODING, "UTF-8");

/**
* Project root that {@link #check(List)} names the resources after. Nothing is read from or
* written to it; the resources only need URIs to resolve the references between the uploads.
*/
private static final Path UNWRITTEN_PROJECT_ROOT = Path.of("unwritten-project");

static {
GenModelPackage.eINSTANCE.eClass();
EValidator.Registry.INSTANCE.put(EcorePackage.eINSTANCE, EcoreValidator.INSTANCE);
Expand All @@ -82,8 +88,30 @@ public class MetamodelProcessor {
public List<GeneratedMetamodel> process(List<UploadedFile> metamodels, Path projectRoot)
throws IOException {
Path ecoreDirectory = ProjectLayout.ecoreDirectory(projectRoot);
Checked checked = checkAndGenerate(metamodels, ecoreDirectory);

Files.createDirectories(ecoreDirectory);
for (Resource resource : checked.resourceSet().getResources()) {
resource.save(SAVE_OPTIONS);
}
return checked.metamodels();
}

/**
* Runs the same checks as {@link #process(List, Path)} without writing anything.
*
* @param metamodels uploaded ecore files
* @return one entry per uploaded metamodel, in upload order
* @throws VsumBuildException when a metamodel is unparsable, invalid, or references a metamodel
* that was not uploaded
*/
public List<GeneratedMetamodel> check(List<UploadedFile> metamodels) {
return checkAndGenerate(metamodels, ProjectLayout.ecoreDirectory(UNWRITTEN_PROJECT_ROOT))
.metamodels();
}

/** Checks the metamodels and generates their genmodels in memory, without saving them. */
private Checked checkAndGenerate(List<UploadedFile> metamodels, Path ecoreDirectory) {
ResourceSet resourceSet = createIsolatedResourceSet();
Map<UploadedFile, EPackage> packages = load(metamodels, resourceSet, ecoreDirectory);
resolveCrossReferences(resourceSet, packages);
Expand All @@ -105,15 +133,16 @@ public List<GeneratedMetamodel> process(List<UploadedFile> metamodels, Path proj
checkGeneratedNames(packages, genModels);
addUsedGenPackages(genModels);

for (Resource resource : resourceSet.getResources()) {
resource.save(SAVE_OPTIONS);
}

return genModels.entrySet().stream()
.map(entry -> describe(entry.getKey(), entry.getValue()))
.toList();
return new Checked(
resourceSet,
genModels.entrySet().stream()
.map(entry -> describe(entry.getKey(), entry.getValue()))
.toList());
}

/** Checked metamodels and their genmodels, all in one resource set that is not saved yet. */
private record Checked(ResourceSet resourceSet, List<GeneratedMetamodel> metamodels) {}

/**
* Creates a resource set that never loads anything from disk or network. All metamodels must be
* uploaded; Ecore's own packages come from the global package registry.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,32 @@ public class ReactionsProcessor {
public List<String> process(
List<UploadedFile> reactions, List<GeneratedMetamodel> metamodels, Path projectRoot)
throws IOException {
List<String> specifications = check(reactions, metamodels);

Path directory = ProjectLayout.reactionsDirectory(projectRoot);
Files.createDirectories(directory);
for (UploadedFile file : reactions) {
String text = file.text();
String normalized = hoistJavaImports(text);
if (normalized.equals(text)) {
Files.write(directory.resolve(file.fileName()), file.content());
} else {
Files.writeString(directory.resolve(file.fileName()), normalized, StandardCharsets.UTF_8);
}
}
return specifications;
}

/**
* Runs the same checks as {@link #process(List, List, Path)} without writing anything.
*
* @param reactions uploaded reactions files
* @param metamodels the checked metamodels the reactions may import
* @return generated change propagation specification class names, one per reactions segment
* @throws VsumBuildException when a file declares no segment, a segment is declared twice, or a
* file imports a metamodel that was not uploaded
*/
public List<String> check(List<UploadedFile> reactions, List<GeneratedMetamodel> metamodels) {
Set<String> knownNsUris = new LinkedHashSet<>();
metamodels.forEach(
metamodel -> metamodel.packages().forEach(pkg -> knownNsUris.add(pkg.nsUri())));
Expand Down Expand Up @@ -127,18 +153,6 @@ public List<String> process(
"The uploaded reactions do not match the uploaded metamodels:",
problems);
}

Path directory = ProjectLayout.reactionsDirectory(projectRoot);
Files.createDirectories(directory);
for (UploadedFile file : reactions) {
String text = file.text();
String normalized = hoistJavaImports(text);
if (normalized.equals(text)) {
Files.write(directory.resolve(file.fileName()), file.content());
} else {
Files.writeString(directory.resolve(file.fileName()), normalized, StandardCharsets.UTF_8);
}
}
return specifications;
}

Expand Down
Loading
Loading