(Recovered from my old Blog).
XStream is a great utility for serializing objects to XML – and then back again.
The default XML output is neat enough – albeit a little verbose (using fully qualified class names for example). There are plenty of tutorials available showing how to use XStream aliases to clean up the output (e.g. Manual Tweaking Output).
However, sometimes it is not enough to just tweak and alias – more serious manipulation of the output stream is required. For example, complicated Collection-based objects come out very cumbersome (but generic – which is the point). Luckily, XStream provides a powerful interface for custom generation (A Converter in XStream-speak).
To fully control how an object is serialised, create a new class which implements the Converter interface:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 |
import com.thoughtworks.xstream.converters.Converter; import com.thoughtworks.xstream.converters.MarshallingContext; import com.thoughtworks.xstream.converters.UnmarshallingContext; import com.thoughtworks.xstream.io.HierarchicalStreamReader; import com.thoughtworks.xstream.io.HierarchicalStreamWriter; public class MyCustomMapConverter implements Converter { @Override public void marshal(Object source, HierarchicalStreamWriter writer, MarshallingContext context) { // TODO } @Override public boolean canConvert(Class clazz) { return clazz.equals(ClassToBeConverted.class); } @Override public Object unmarshal(HierarchicalStreamReader reader, UnmarshallingContext context) { // TODO } } |
As can be seen above, the canConvert method tells XStream which objects should use this converter. The other two methods are called when converting objects to XML (marshal) or converting XML to objects (unmarshal).
Marshalling the object is achieved by starting and ending Nodes, while populating their attributes and values. So for example:
|
1 2 3 4 5 6 7 8 |
@Override public void marshal(Object source, HierarchicalStreamWriter writer, MarshallingContext context) { for (RouterConfigRuleMap routerConfigRuleMap : routerConfigRuleMapSet.getRouterConfigRuleMapSet()) { writer.startNode(“routetype”); writer.addAttribute(“type”, routerConfigRuleMap.getRouteType().toString()); writer.endNode(); } |
will iterate through a collection generating the following output:
|
1 2 |
<routetype type=“example” /> <routetype type=“foo” /> |
These patterns can become arbitrarily complex.
Unmarshalling is a little more complicated. XStream will work out which (registered – see later) Converter to use by matching the node to the class (in my head these seems like an extremely difficult task… I’m not sure how XStream has implemented this – maybe I should look into this!) The node (and all children) will be passed to the unmarshal method.
It is up to us to define how the target object is populated from these nodes. Methods are provided to:
Check if the node has children (reader.hasMoreChildren())
Move down to the child level (reader.moveDown())
Move back up to the parent level (reader.moveUp())
The moveUp/Down methods can be called as many times as necessary to walk the tree.
I provide a full example as I couldn’t find many good ones on the net:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 |
@Override public Object unmarshal(HierarchicalStreamReader reader, UnmarshallingContext context) { RouterConfigRuleMapSet routerConfigRuleMapSet = new RouterConfigRuleMapSet(); while (reader.hasMoreChildren()) { reader.moveDown(); RouterConfigRuleMap routerConfigRuleMap = new RouterConfigRuleMap(); routerConfigRuleMap.setRouteType(RouteType.valueOf(reader.getAttribute(“type”))); while (reader.hasMoreChildren()) { reader.moveDown(); RouterConfigRule routerConfigRule = new RouterConfigRule(); if (reader.getAttribute(“extractor”) != null) { routerConfigRule.setExtractor(reader.getAttribute(“extractor”)); } if (reader.getAttribute(“formatter”) != null) { routerConfigRule.setFormatter(reader.getAttribute(“formatter”)); } if (reader.getAttribute(“distributor”) != null) { routerConfigRule.setDistributor(reader.getAttribute(“distributor”)); } routerConfigRuleMap.putRouterConfigRule(reader.getAttribute(“name”), routerConfigRule); reader.moveUp(); } reader.moveUp(); routerConfigRuleMapSet.addRouterConfigRuleMapSet(routerConfigRuleMap); } return routerConfigRuleMapSet; } |
Out of completeness, here is the equivalent marshal implementation:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 |
@Override public void marshal(Object source, HierarchicalStreamWriter writer, MarshallingContext context) { RouterConfigRuleMapSet routerConfigRuleMapSet = (RouterConfigRuleMapSet)source; for (RouterConfigRuleMap routerConfigRuleMap : routerConfigRuleMapSet.getRouterConfigRuleMapSet()) { writer.startNode(“routetype”); writer.addAttribute(“type”, routerConfigRuleMap.getRouteType().toString()); for (Object routerConfig : routerConfigRuleMap.routerConfigRuleMap.entrySet()) { Entry<String, RouterConfigRule> entry = (Entry<String, RouterConfigRule>) routerConfig; RouterConfigRule routerConfigRule = entry.getValue(); writer.startNode(“routename”); writer.addAttribute(“name”, entry.getKey().toString()); if (routerConfigRule.getExtractor() != null) { writer.addAttribute(“extractor”, routerConfigRule.getExtractor()); } if (routerConfigRule.getFormatter() != null) { writer.addAttribute(“formatter”, routerConfigRule.getFormatter()); } if (routerConfigRule.getDistributor() != null) { writer.addAttribute(“distributor”, routerConfigRule.getDistributor()); } writer.endNode(); } writer.endNode(); } } |
To register the Converter simply add the following line when you instantiate the XStream object:
|
1 2 |
XStream stream = new XStream(); stream.registerConverter(new RouterConfigMapConverter()); // NEW LINE |