For our project, the graphical Tweetflow editor for Android, we also wanted to implement the functionality to save created Tweetflows and reopen them later. Therefore we had to find a possibility to save our plain old Java object (POJOs) on the devices storage or in a database and to recreate them afterwards.
After some research we stumbled upon the “Simple” XML serialization framework, which provides all we need for our project in a very simple way. And the framework really lived up to its name. In the end it took less than 50 lines of code to handle the (de-)serialization of our POJOs from/to a XML file. And apart from the annotations needed for Simple we didn’t have to change our existing classes at all.
The Simple homepage provides a comprehensive list of examples that cover everything you need to get started and some advanced examples. But even with this helpful tutorials we had to deal with some problems which we want to discuss in this blog post.
But first we take a look at some of the basic examples from the tutorials to understand how “Simple” works:
At first we need to add some annotations to all the classes that we want to serialize.
@Root
public class Example {
@Element
private String text;
@Attribute
private int index;
public Example() {
super();
}
public Example(String text, int index) {
this.text = text;
this.index = index;
}
public String getMessage() {
return text;
}
public int getId() {
return index;
}
}
The most important annotations are @Root, @Attribute and @Element. Attributes and elements can be marked optional with the addition of required=false. The variable name is automatically taken for the names of elements and attributes in the xml document. This can be changed with name="foobar". As these annotations are rather self-explanatory lets see how we can serialize this object:
Serializer serializer = new Persister();
Example example = new Example("Example message", 123);
File result = new File("example.xml");
serializer.write(example, result);
This produces the following output:
<example index="123"> <text>Example message</text> </example>
Really Simple, isn’t it? Deserialization is just a matter of some few lines too:
Serializer serializer = new Persister();
File source = new File("example.xml");
Example example = serializer.read(Example.class, source);
Now some code parts from our application:
@Root
public class TweetFlow {
@Attribute
private String mName = "";
@Attribute
private Integer mElemCounter;
@ElementMap(entry="element", key="id", attribute=true, required=false, empty=true)
private HashMap<Integer, AbstractElement> mElements;
//constructors and methods here ......
The most interesting part is the annotation @ElementMap. This annotation is used to serialize Maps. entry tells Simple how to name the entries in the xml file, key names the key-entries in the map and attribute=true marks them to be saved as attributes instead of sub-elements. required=false marks this HashMap as optional and empty=true tells Simple to instantiate an empty HashMap instead of leaving the variable null if the element does not exist in the xml document.
The maps value type is AbstractElement. This is the abstract base type for all drawable elements in our editor. Simple changes this type with the actual type of the mapped elements when they are written to the xml document.
public abstract class AbstractElement {
@Attribute
protected Integer mId;
//Dimensions
@Attribute
protected int mX;
@Attribute
protected int mY;
@Attribute
protected int mWidth;
@Attribute
protected int mHeight;
@Element(required=false)
protected AbstractElement mClosedSequenceNext = null;
// @Element(required=false)
//NOT as @Element, set with TweetFlow.updateClosedSequences() after deserialization
protected AbstractElement mClosedSequencePrev = null;
// ......
As you can see here each element contains references to its next or previous element which are set if the element is in a closed sequence. Normally this cyclic references are no problem for “Simple” with some minor adjustments to the (de-)serialization method.
final File file = new File("output.xml");
//CycleStrategy automatically handles cyclic references
Strategy strategy = new CycleStrategy("x_id", "x_ref");
Serializer serializer = new Persister(strategy);
serializer.write(tweetflow, file);
In our case this didn’t work and we had to set the reference to mClosedSequencePrev manually after deserializing the xml file. We where quite stunned, because Simples CycleStrategy is exactly for this kind of cyclic references and it did work in our small Simple-Test project. Lets take a closer look at a subclass of AbstractElement and then we’ll see why CycleStrategy let us down in this case.
public class ServiceRequest extends AbstractElement {
//....
public ServiceRequest(@Attribute(name="mId") Integer id,
@Attribute(name="mX") int x,
@Attribute(name="mY") int y) {
super(id, x, y, 80, 80);
}
This strange annotations in the constructor of ServiceRequest tell Simple to use constructor injection. Instead of creating the object and assigning each variable its values afterwards Simple needs the values to instantiate the specific object.
In our case each AbstractElement holds a reference to its successor and predecessor. Simple assigns every object an ID and links these objects via their ID in the xml document. This means that these objects are sometimes not stored as subelements, but as a numerical references. And this creates problems if you havecyclic references in combination with constructor injection.
Simple knows, that object A has a reference to object B and vice-versa. So if it wants to deserialize A, it needs B first. Simple knows the type of B, but cannot instantiate B as an “empty” object because it needs Bs values for the constructor injection. But since B is only a numerical reference in the xml, Simple does not know this values yet. And the problem is the same the other way around for Bs reference to A.
The problem could be solved by providing an empty constructor without any parameters, or, like we did it in our program, create only one reference at first and create the second one after all objects have been created.
We hope this was not too confusing (and long), all in all it is really Simple 
If you ever need a serialization framework for Java you should definitely give Simple a try. It is very lightweight which is a huge bonus if you intend to use it for an Android app and the examples on the homepage provide you with everything to get started.
Matthias Neumayr
Martin Perebner