|
|
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](https://github.com/bazaarvoice/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(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. mvn -Dmaven.test.skip=true package
|
|
|
2. java -jar VadereSimulator/target/vadere-console.jar migrate -r VadereModelTests/ (**Note:** Provide the argument `--target-version major.minor` to use a specific version and not the latest version from `Version.java`).
|
|
|
3. git clean -n
|
|
|
4. 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));
|
|
|
``` |
|
|
\ No newline at end of file |