In the upcoming posts I will give three examples of how to implement backwards compatibility using hbm mappings.
In this post I start with a simple refactoring: a 'Product' class for which a boolean property was renamed and, as a bonus, also negated.
So, originally a product was marked as 'available', but it was later decided it would be more logical to use a 'Discontinued' flag. This is not just a simple rename! We need to do something equivalent to 'Discontinued = !Available' when loading products from the old database. Specifically, we need to write a nhibernate HBM mapping file which reads the old database format into the new object model.
The old database format is as follows:
And you can imagine the original HBM with which this was saved would look something like this:
<?xml version="1.0" encoding="utf-8" ?>
<hibernate-mapping xmlns="urn:nhibernate-mapping-2.2" assembly="..." namespace="...">
<class name="Product">
<id name="Id"> <generator class="guid" /> </id>
<property name="Name" />
<property name="Category" />
<property name="Available"/>
</class>
</hibernate-mapping>
The new HBM looks something like this:
<?xml version="1.0" encoding="utf-8" ?>
<hibernate-mapping xmlns="urn:nhibernate-mapping-2.2" assembly="..." namespace="...">
<class name="Product">
<id name="Id"> <generator class="guid" /> </id>
<property name="Name" />
<property name="Category" />
<property name="Discontinued"/>
</class>
</hibernate-mapping>
To migrate from the old database to the new object model, we must create a special mapping. This mapping will only be used for loading, not for saving, so we can use some special features like embedding SQL queries into the HBM.
Let's start by writing the basics. We can map most properties 1-to-1, as you can see here:
<?xml version="1.0" encoding="utf-8" ?>
<hibernate-mapping xmlns="urn:nhibernate-mapping-2.2" assembly="..." namespace="...">
<class name="Product">
<id name="Id"> <generator class="guid" /> </id>
<property name="Name" />
<property name="Category" />
<property name="Discontinued" ????what to do here???? />
</class>
</hibernate-mapping>
Less trivial is how to retrieved the correct value for the 'Discontinued' property. We must keep in mind that we can only map to new properties, so we cannot have a property with name="Available" here. The 'Available' value is however available in the database, so in this case we can solve it by using the 'formula' field inside a property tag, to insert SQL queries and logic to get values from the database.
Specifically, we can do the following:
<property name="Discontinued" formula="( Available = 0 )"/>
To understand why this works, it is important to understand how NHibernate processes these formulas. NHibernate inserts the formula as a subquery into the larger SQL. This is the cleaned-up version of what NHibernate generates:
SELECT product.Id, product.Name, product.Category, ( product.Available = 0 ) FROM Product product WHERE product.Id=?