Five Minute Tutorial

We demonstrate usage of this tool with a simple tutorial. Assume a Task class below with a prioritized field indicating whether it is a prioritized task:

package example;

public class Task {
  public boolean prioritized;
}

With XStream, we can serialize object of this class to XML like below:

import com.thoughtworks.xstream.XStream;

Task task = new Task();
task.prioritized = true;
String xml = new XStream().toXML(task);
saveXmlToFileOrDatabase(xml);

The resulting XML will be:

<example.Task>
  <prioritized>true</prioritized>
</example.Task>

And you can deserialize the XML to get back task object:

import com.thoughtworks.xstream.XStream;
import com.thoughtworks.xstream.io.xml.DomDriver;

String xml = readXmlFromFileOrDatabase();
Task task = (Task)(new XStream(new DomDriver()).fromXML(xml));

Everything is fine. Now we find a prioritized flag is not enough, so we enhance the Task class to use a numeric priority field ranging from 1 to 10:

package example;

public class Task {
  public int 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 handles the migration. With XMT, serialization of task object can be written as:

package example;
import com.pmease.commons.xmt.VersionedDocument;

Task task = new Task();
task.prioritized = true;
String xml = VersionedDocument.fromBean(task).toXML();
saveXmlToFileOrDatabase(xml);

The resulting XML will be:

<?xml version="1.0" encoding="UTF-8"?>

<example.Task version="0">
  <prioritized>true</prioritized>
</example.Task>

Compared with the XML generated by directly using XStream, an additional attribute version is added to the root element indicating version of the class generating this XML. The value is set to 0 unless there are migration methods defined in the class as we will introduce below.

The XMT version of deserializing task object from xml is:

Five Minute Tutorial

Labels