From time to time there is a moment when we have to deal with XML data. And most of the time it is not the happiest day in our life. There is even a term “XML hell” describing situation when programmer has to deal with many XML configuration files that are hard to comprehend. But, like it or not, sometimes we have no choice, mostly because specification from client says something like “use configuration written in XML file” or something similar. And in such cases, XStream comes with its very cool features that make dealing with XML really less painful.



XStream is a small library to serialize data between Java objects and XML. It’s lightweight, small, has nice API and what is most important, it works with and without custom annotations that we might be not allowed to add when we are not the owner of Java classes.

First example

Suppose we have a requirement to load configuration from xml file:

And we want to load it into Configuration object:

So basically what we have to do is:

And that’s all, easy peasy 🙂

Something more serious

Ok, but previous example is very basic so now let’s do something more complicated: real XML returned by real WebService.

What we have here is simple list of bans written in XML. We want to load it into collection of Ban objects. So let’s prepare some classes (getters/setters/toString omitted):

As you can see there is some naming and type mismatch between XML and Java classes (e.g. field name1->firstName, dateOfUpdate is String not a Date), but it’s here for some example purposes.

So the goal here is to parse XML and get Data object with populated collection of Ban instances containing correct data. Let’s see how it can be achieved.

Parse with annotations

First, easier way is to use annotations. And that’s the suggested approach in situation when we can modify Java classes to which XML will be mapped. So we have:

And actual parsing logic is very short:

As you can see annotations are very easy to use and as a result final code is very concise. But what to do in situation when we can’t modify mapping classes? We can use different approach that doesn’t require any modifications in Java classes representing XML data.

Parse without annotations

When we can’t enrich our model classes with annotations, there is another solution. We can define all mapping details using methods from XStream object:


As you can see XStream allows to easily convert more complicated XML structures into Java objects, it also gives a possibility to tune results by using different names if this from XML doesn’t suit our needs.
But there is one thing should catch your attention: we are converting XML representing a Date into raw String which isn’t quite what we would like to get as a result. That’s why we will add converter to do some job for us.

Using existing custom type converter

XStream library comes with set of built converters for most common use cases. We will use DateConverter. So now our class for Ban looks like that:

And to use DateConverter we simply have to register it with date format that we expect to appear in XML data:

and that’s it. Now instead of String our object is populated with Date instance. Cool and easy! But what about classes and situations that aren’t covered by existing converters? We could write our own.

Writing custom converter from scratch

Assume that instead of dateOfUpdate we want to know how many days ago update was done:

Of course we could calculate it manually for each Ban object but using converter that will do this job for us looks more interesting. Our DaysAgoConverter must implement Converter interface so we have to implement three methods with signatures looking a little bit scary:

Last one is easy as we will convert only Integer class. But there are still two methods left with these HierarchicalStreamWriter, MarshallingContext, HierarchicalStreamReader and UnmarshallingContext parameters. Luckily, we could avoid dealing with them by using AbstractSingleValueConverter that shields us from so low level mechanisms. And now our class looks much better:

Additionally we must override method toString(Object obj) defined in AbstractSingleValueConverter as we want to store Date in XML calculated from Integer, not a simple Object.toString value which would be returned from default toString defined in abstract parent.


Code below is pretty straightforward, but most interesting lines are commented. I’ve skipped all validation stuff to make this example shorter.

To use our custom converter for a specific field we have to inform about it XStream object using registerLocalConverter:

We are using “local” method to apply this conversion only to specific field and not to every Integer field in XML file. And after that we will get our Ban objects populated with number of days instead of Date.


That’s all what I wanted to show you in this post. Now you have basic knowledge about what XStream is capable of and how it can be used to easily map XML data to Java objects If you need something more advanced, please check project official page as it contains very good documentation and examples.