GitLab

The Migration assistant helps to update existing scenario files. For instance, to update the "release" attribute, to rename existing attributes or to include a new attribute with a specific default value. The Vadere scenario files are simple JSON documents.

The migration assistant is encapsulated as Java package org.vadere.simulator.projects.migration and was developed in two phases. Until scenario file version 0.7 (indicated as "release" : "0.7"), the helper library Jolt was used to transform a scenario file. From scenario file version 0.8 on, the self written helper class SimpleJsonTransformation is used to transform a scenario file.

Steps to Set Up a New Migration

1. Add new version number to enum Version.
2. Create new Java File JsonTransformVxToVy.java (or copy existing one) under VadereSimulator/src/org/vadere/simulator/projects/migration/jsontranformation/json.
3. The created file from (2) must extend SimpleJsonTransformation.
4. Apply the annotation @MigrationTransformation with correct targetVersionLabel to the created file from (2). Note: This is required to auto-generate factory methods properly.
5. Implement the required transformation functions by obeying the functional interface JsonTransformationHook. Tip: Use the helper class JsonNodeExplorer to parse the given JSON tree.
6. Call functions from (5) in any order within applyTransformation or use initDefaultHooks() to add them to the pre or postHook in any order.

The following snippet demonstrates a new migration:

@MigrationTransformation(targetVersionLabel = "0.9")
public class JsonTransformV8ToV9 extends SimpleJsonTransformation {

    public JsonTransformV8ToV9() {
        super(Version.V0_9);
    }

    @Override
    protected void initDefaultHooks() {
        addPostHookLast(this::renameFinishTime);
        addPostHookLast(this::sort);
    }
    
    public JsonNode renameFinishTime(JsoNode node) throws MigrationsException {
        JsonNode field = pathMustExist(node, "scenario/attributesSimulation/finishTime"); // see JsonNodeExplorer
        renameField((ObjectNode)field, "finishTime", "endTime"); // see JsonNodeExplorer
        return node;
    }

}

Migration Helpers

Update Existing Scenario Files

vadere-console.jar allows to update scenario files to the latest or any given version number. Use following steps:

1. Add new version number to Version.java
2. mvn clean
3. mvn package
4. java -jar VadereSimulator/target/vadere-console.jar migrate -r .
   • Use the repository root as target directory (.) so that all scenarios get migrated (also the one which are used for unit tests).
   • Provide the argument --target-version major.minor to use a specific version and not the latest version from Version.java.
5. git clean -n
6. git clean -f (to delete <scenario_file>.scenario.legacy which is created by the migration assistant)

JsonNodeExplorer

Contains usefull default implementations to access, travers and modife a JsonNode. Methods such as pathMustExist will throw a MigrationsException. This Interface also provides Iterators to iterate over all Processors present in the Json representation. Also Filterd Iterators exist.

TestJsonNodeExplorer and TestJsonNodeHelper

Sames as JsonNodeExplorer but with Junit Assertions insted of MigrationsException. This Interfaces also contains Hamcrest Matcher to simplify JsonTransformation considerably. For instance measurementAreaExists ist a HamcrestMatcher which searches the complete scearioJson for the existance of a MeasurementArea based on its id.

assertThat(jsonNew, measurementAreaExists(measurementAreaId));