Data Migration Tool
Assume a Task class below with a prioritized field indicating whether it is a prioritized task:
With XStream, we can serialize object of this class to XML like below:
The resulting XML will be:
And you can deserialize the XML to get back task object:
Everything is fine. Now we find that a prioritized flag is not enough, so we enhance the Task class to be able to distinguish between high priority, medium priority and low priority:
However deserialization of previously saved xml is no longer possible since the new Task class is not compatible with previous version.
XMT comes to rescue: it introduces class VersionedDocument to version serialized XMLs and handle the migration. With XMT, serialization of task object can be written as:
For task class of the old version, the resulting XML will be:
Compared with the XML generated previously with XStream, an additional attribute version is added to the root element indicating version of the XML. The value is set to 0 unless there are migration methods defined in the class as we will introduce below.
When Task class is evolved to use enum based priority field, we add a migrate method like below:
Migration methods need to be declared as a private method with name in form of migrateXXX, where XXX is a number indicating current version of the class. Here method migrate1 indicates that current version of the task class is of "1", and the method migrates the XML from version 0 to 1. The XML to be migrated is passed as a VersionedDocument object which implements dom4j Document interface and you may use dom4j to migrate it to be compatible with current version of the class. The versions parameter is used to handle the migration if class inheritance hierarchy is changed and will be introduced in class hierarchy migration chapter.
With this migration method defined, you can now safely deserialize the task object from XML:
The deserialization works not only for XML of the old version, but also for XML of the new version. At deserialization time, XMT compares version of the XML (recorded in the version attribute as we mentioned earlier) with current version of the class (maximum suffix number of various migrate methods), and run applicable migrate methods one by one. In this case, if a XML of version "0" is read, method migrate1 will be called; if a XML of version "1" is read, no migration methods will be called since it is already up to date.
As class keeps evolving, more migration methods can be added to the class by increasing suffix number of latest migration method. For example, let's further enhance our task class so that the priority field is taking a numeric value ranging from 1 to 10. We add another migrate method to the Task class to embrace the change:
This method only handles the migration from version "1" to version "2", and we do not need to care about version "0" any more, since XML of version "0" will first be migrated to version "1" by calling method migrate1 before running this method.
This simple tutorial gives you the idea of how to migrate field change of classes. XMT can handle much complicated scenarios, such as migrating data defined in multiple tiers of class hierarchy, addressing class hierarchy change, etc. These topics are covered in other chapters.