This post describes a design for implementing backwards-compatibility in deltashell.
Backwards-compatibility : The ability to open project files written by an older version of the application in the current application.
Global idea / setup
...
Both framework and plugin2 have new versions. DeltaShell has to find to 1.2 to 1.3 mappings for framework and 1.1 to 1.2 mappings for plugin2. Since not all entity mappings change the logic is as follows.*
Per mapping file:*
1 Try to find exact match for the version that is in the db. So for entity River of Plugin2 try to find the mapping river.hbm.1.1.xml
2 If this is not found try to find the first earlier version and use this.
3 If none found use
This section and the implemented logic has been updated June 2012
The rule per mapping file is simple:
- Take the first mapping file with a version equal or more recent than the persisted version.
Note Revision / build version numbers are ignored; 3.0.5 is treated as 3.0. The idea behind this is that file format changes should only occur in major or minor versions.
More elaborate, in a chart:
So how does this affect plugin development?
If you release a version which you want to support you should include a test reading a project file of that version. So when you release your plugin 1.5 you should write a test called ReadVersion1_5 in your plugin that reads a project that covers all possible mappings you have in your plugin. You should check you get everything back from the project as you expect it. The dsproj file is checked into svn and the test should work as nothing changed yet. All is well....
After a while you want to refactor your class A. You also change the mapping A.hbm.xml. But the test ReadVersion1_5 you wrote on release now fails because reading the old db with the new a.hbm.xml does not work! What to do? You can chose not to refactor A and do something else OR you could add a A.1.5.hbm.xml mapping that converts the old db to the new object. Once you check in that new mapping file *ReadVersion1.5 should use that specific file (instead of A.hbm.xml) and the test should pass again.
So for a plugin it boils down to 4 points:
1 Write a ignored (not run on BS) test that can create a dsproj file with all persistent objects you have in your plugin. You create a 'representative' project here. Update this test as your plugin evolves and add the category [BackwardCompatibility]
2 If you have a release with file-format changes run test 1) and copy the result to the release version. Write a test that reads in that project file and add the category [BackwardCompatibility]
For example if you release 1.1 you should run the test of 1) and copy the result to project1_1.dsproj + data. Check in this project and write a test ReadVersion1_1 that reads this project. You will never change this checked in project again.
3 If the test of 2) breaks add version specific mappings until the test passes again.
4 If you longer support a version delete the test and the mapping you created for it the 'normal' hbm.xml.If the version of the project file is older than the oldest legacy hbm this version is not supported and a message should be shown. For example you have a db 0.4 but mappings only support back to 0.6. So 0.4 is no longer supported and the load cannot continue.