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

The idea is to use custom hbm.xml mapping to convert older project databases to the current object model. For example a plugin has made a release 1.0 which should be supported. Now if the mappings change during further development something has to be done to read the old projects. We need specific mappings to read the old files next to the current mappings. The situation would be as follows:

So the Person.hbm.1.0.xml describes the mapping of files written with 1.0 to the current version of the person. This mapping wil change as the Person evolves and we still want to support read old project files. NHibernate has a rich feature-set to get the data from the old schema to the new objects such as formulas, custom sql, usertypes etc. Another advantage of this approach is that backwards compatibility is solved using stand NHibernate technology and not DS specific stuff.

What happens when an old project gets openened?

If Deltashell opens an old project it creates a session for that version of the DB. After that all objects are migrated to a new session with the current configuration. Then when the project is saved the database is in a new format.

How does DS know which mapping to use?

Each project database contains a table with plugin version information with which the db was written. The version is the same as used for the plugin assembly. This could look like this:

Now development continues and breaking changes occur. This could look like this :

When the project is saved the following information is entered in the versions table

Now when that project is loaded the information is this:

Both framework and plugin2 have new versions. DeltaShell has find to 1.2 to 1.3 mappings for framework and 1.1 to 1.2 mappings for plugin2. Since not all entities 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 the 'normal' hbm.xml.