|
|
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.
|
|
|
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 `TargetVersionVX_Y.java` (or copy existing one) under `VadereSimulator/src/org/vadere/simulator/projects/migration/jsontranformation/json`.
|
|
|
2. Create new Java File `TargetVersionVX_Y.java` (or copy the 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.
|
|
|
4. Apply the annotation `@MigrationTransformation` with the 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 {
|
|
|
@MigrationTransformation(targetVersionLabel = "X.Y")
|
|
|
public class TargetVersionX_Y extends SimpleJsonTransformation {
|
|
|
|
|
|
public JsonTransformV8ToV9() {
|
|
|
super(Version.V0_9);
|
|
|
public TargetVersionX_Y() {
|
|
|
super(Version.VX_Y);
|
|
|
}
|
|
|
|
|
|
@Override
|
... | ... | @@ -39,7 +39,7 @@ public class JsonTransformV8ToV9 extends SimpleJsonTransformation { |
|
|
|
|
|
### Update Existing Scenario Files
|
|
|
|
|
|
vadere-console.jar allows to update scenario files to the latest or any given version number. Use following steps:
|
|
|
vadere-console.jar allows updating scenario files to the latest or any given version number. Use the following steps:
|
|
|
|
|
|
1. Add new version number to Version.java
|
|
|
2. mvn clean
|
... | ... | @@ -58,9 +58,9 @@ 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
|
|
|
Sames as JsonNodeExplorer but with Junit Assertions instead of MigrationsException. This interface
|
|
|
also contains Hamcrest Matcher to simplify JsonTransformation considerably. For instance
|
|
|
`measurementAreaExists` ist a HamcrestMatcher which searches the complete scearioJson for the existance
|
|
|
`measurementAreaExists` is a HamcrestMatcher that searches the complete scearioJson for the existence
|
|
|
of a MeasurementArea based on its id.
|
|
|
|
|
|
```
|
... | ... | @@ -68,5 +68,5 @@ assertThat(jsonNew, measurementAreaExists(measurementAreaId)); |
|
|
```
|
|
|
|
|
|
### Test `JsonMigrationAssistantTest`
|
|
|
Note that one does not need to create a test scenario to check whether the migration from v0.1 to new target version works.
|
|
|
Note that one does not need to create a test scenario to check whether the migration from v0.1 to the new target version works.
|
|
|
`JsonMigrationAssistantTest` ensures that: automatically migrates the test project stored in `VadereSimulator/testResources/migration/testProject_v0.1`. |
|
|
\ No newline at end of file |