Annotations Tutorial
Motivation
Sometimes it can get tedious to call all those XStream aliases/register converter methods or you might simply like the new trend on configuring POJOs: Java annotations.
This tutorial will show you how to use some of the annotations provided by XStream in order to make configuration easier. Let's start with a custom Message class:
package com.thoughtworks.xstream;
package com.thoughtworks.xstream;
public class RendezvousMessage {
private int messageType;
public RendezvousMessage(int messageType) {
this.messageType = messageType;
}
}Let's code the XStream calls which generate the XML file:
package com.thoughtworks.xstream;
public class Tutorial {
public static void main(String[] args) {
XStream stream = new XStream();
RendezvousMessage msg = new RendezvousMessage(15);
System.out.println(stream.toXML(msg));
}
}
Results in the following XML:
<com.thoughtworks.xstream.RendezvousMessage> <messageType>15</messageType> </com.thoughtworks.xstream.RendezvousMessage>
Aliasing Annotation
The most basic annotation is the one responsible for type and field aliasing: @XStreamAlias. Let's annotate both our type and field and run the tutorial method again:
@XStreamAlias("message")
class RendezvousMessage {
@XStreamAlias("type")
private int messageType;
public RendezvousMessage(int messageType) {
this.messageType = messageType;
}
}
In some strange way, the result is the same. What happened here? XStream does not read this annotation by default as it would be impossible to deserialize the XML code. Therefore we need to tell XStream to read the annotations from this type:
public static void main(String[] args) {
XStream stream = new XStream();
xstream.processAnnotations(RendezvousMessage.class);
RendezvousMessage msg = new RendezvousMessage(15);
System.out.println(stream.toXML(msg));
}
Note that we have called the processAnnotations method of XStream. This method registers all aliases annotations in the XStream instance passed as first argument. You may also use the overloaded version of this method taking an array of types. The resulting XML is now what we have expected:
<message> <type>15</type> </message>
If you let XStream process the annotations of a type, it will also process all annotations of the related types i.e. all super types, implemented interfaces, the class types of the members and all their generic types.
Implicit Collections
Let's add a List of content to our RendezvousMessage. We desire the same functionality obtained with implicit collections:
@XStreamAlias("message")
class RendezvousMessage {
@XStreamAlias("type")
private int messageType;
private List<String> content;
public RendezvousMessage(int messageType, String ... content) {
this.messageType = messageType;
this.content = Arrays.asList(content);
}
}
public static void main(String[] args) {
XStream stream = new XStream();
xstream.processAnnotations(RendezvousMessage.class);
RendezvousMessage msg = new RendezvousMessage(15, "firstPart","secondPart");
System.out.println(stream.toXML(msg));
}
The resulting XML shows the collection name before its elements:
<message>
<type>15</type>
<content class="java.util.Arrays$ArrayList">
<a class="string-array">
<string>firstPart</string>
<string>secondPart</string>
</a>
</content>
</message>
This is not what we desire therefore we will annotate the content list to be recognized as an implicit collection:
@XStreamAlias("message")
class RendezvousMessage {
@XStreamAlias("type")
private int messageType;
@XStreamImplicit
private List<String> content;
public RendezvousMessage(int messageType, String... content) {
this.messageType = messageType;
this.content = Arrays.asList(content);
}
}
Resulting in an XML which ignores the field name (content) of the list:
<message>
<type>15</type>
<a class="string-array">
<string>firstPart</string>
<string>secondPart</string>
</a>
</message>
We are almost there... we still want to remove the 'a' tag, and define each content part with the tag 'part'. In order to do so, let's add another attribute to our implicit collection annotation. The attribute field defines the name of the tag used for data contained inside this collection:
@XStreamAlias("message")
class RendezvousMessage {
@XStreamAlias("type")
private int messageType;
@XStreamImplicit(itemFieldName="part")
private List<String> content;
public RendezvousMessage(int messageType, String... content) {
this.messageType = messageType;
this.content = Arrays.asList(content);
}
}
Resulting in a cleaner XML:
<message> <type>15</type> <part>firstPart</part> <part>secondPart</part> </message>
The implicit annotation can also be used for arrays and maps. In the latter case you should provide the field name of the values that are used as key of the map.
Local Converters
Let's create another attribute which defines the timestamp when the message was created and one to flag special importance of the message:
@XStreamAlias("message")
class RendezvousMessage {
@XStreamAlias("type")
private int messageType;
@XStreamImplicit(itemFieldName="part")
private List<String> content;
private boolean important;
private Calendar created = new GregorianCalendar();
public RendezvousMessage(int messageType, boolean important, String... content) {
this.messageType = messageType;
this.important = important;
this.content = Arrays.asList(content);
}
}
Resulting in the following xml:
<message>
<type>15</type>
<part>firstPart</part>
<part>secondPart</part>
<important>false</important>
<created>
<time>1154097812245</time>
<timezone>America/Sao_Paulo</timezone>
</created>
</message>
Now we face the following problem: We want to use a custom converter locally for this Calendar, but only for this Calendar, this exact field in this exact type. Easy... let's annotate it with the custom converter annotation:
@XStreamAlias("message")
class RendezvousMessage {
@XStreamAlias("type")
private int messageType;
@XStreamImplicit(itemFieldName="part")
private List<String> content;
private boolean important;
@XStreamConverter(SingleValueCalendarConverter.class)
private Calendar created = new GregorianCalendar();
public RendezvousMessage(int messageType, String... content) {
this.messageType = messageType;
this.content = Arrays.asList(content);
}
}
Let's create the custom converter:
public class SingleValueCalendarConverter implements Converter {
public void marshal(Object source, HierarchicalStreamWriter writer,
MarshallingContext context) {
Calendar calendar = (Calendar) source;
writer.setValue(String.valueOf(calendar.getTime().getTime()));
}
public Object unmarshal(HierarchicalStreamReader reader,
UnmarshallingContext context) {
GregorianCalendar calendar = new GregorianCalendar();
calendar.setTime(new Date(Long.parseLong(reader.getValue())));
return calendar;
}
public boolean canConvert(Class type) {
return type.equals(GregorianCalendar.class);
}
}
And we end up with the converter being used and generating the following XML:
<message> <type>15</type> <part>firstPart</part> <part>secondPart</part> <important>false</important> <created>1154097812245</created> </message>
Additionally we want to format the importance flag not with a technical true or false, but with a natural yes or no. Fortunately the BooleanConverter supports alternate format styles, but how can we use an annotation to register a new instance locally? The XStreamConverter annotation uses some lightweight dependency injection mechanism to match given arguments with the parameters of available constructors. That way we can write now:
@XStreamAlias("message")
class RendezvousMessage {
@XStreamAlias("type")
private int messageType;
@XStreamImplicit(itemFieldName="part")
private List<String> content;
@XStreamConverter(value=BooleanConverter.class, booleans={false}, strings={"yes", "no"})
private boolean important;
@XStreamConverter(SingleValueCalendarConverter.class)
private Calendar created = new GregorianCalendar();
public RendezvousMessage(int messageType, boolean important, String... content) {
this.messageType = messageType;
this.important = important;
this.content = Arrays.asList(content);
}
}
The BooleanConverter has an additional constructor with two string values expressing true and false and a third argument to ignore case of these values. Therefore we have added all 3 arguments to the annotation. The sequence of the arguments is only important for same types. As result we have now:
<message> <type>15</type> <part>firstPart</part> <part>secondPart</part> <important>no</important> <created>1154097812245</created> </message>
See the Javadoc of the XStreamConverter annotation what more arguments are provided implicitly.
Attributes
The client may asks for the type tag and the importance flag to be an attribute inside the message tag, as follows:
<message type="15" important="no"> <part>firstPart</part> <part>secondPart</part> <created>1154097812245</created> </message>
All you need to do is add the @XStreamAsAttribute annotation:
@XStreamAlias("message")
class RendezvousMessage {
@XStreamAlias("type")
@XStreamAsAttribute
private int messageType;
@XStreamImplicit(itemFieldName="part")
private List<String> content;
@XStreamAsAttribute
@XStreamConverter(value=BooleanConverter.class, booleans={false}, strings={"yes", "no"})
private boolean important;
@XStreamConverter(SingleValueCalendarConverter.class)
private Calendar created = new GregorianCalendar();
public RendezvousMessage(int messageType, boolean important, String... content) {
this.messageType = messageType;
this.important = important;
this.content = Arrays.asList(content);
}
}
Field as Text Value
Sometimes it is desirable to use a single field as text value for a XML element and all other fields should be written as attributes. XStream delivers the ToAttributedValueConverter, that will write a type with this form:
@XStreamAlias("message")
@XStreamConverter(value=ToAttributedValueConverter.class, strings={"content"})
class RendezvousMessage {
@XStreamAlias("type")
private int messageType;
private List<String> content;
@XStreamConverter(value=BooleanConverter.class, booleans={false}, strings={"yes", "no"})
private boolean important;
@XStreamConverter(SingleValueCalendarConverter.class)
private Calendar created = new GregorianCalendar();
public RendezvousMessage(int messageType, boolean important, String... content) {
this.messageType = messageType;
this.important = important;
this.content = Arrays.asList(content);
}
}
Unfortunately our little example does not work! Although we register the converter with the XStreamConverter annotation and provide with its arguments the field name, the conversion will fail later on. To use this converter you have to respect the implicit requirement: Any field (derived or not) has to be expressed as a single string i.e. technically XStream has to use a SingleValueConverter. In our case we have a list of strings that prevent the conversion. Therefore we have to use either a custom converter that transforms this list into a single string or we use for simplicity a simple string here:
@XStreamAlias("message")
@XStreamConverter(value=ToAttributedValueConverter.class, strings={"content"})
class RendezvousMessage {
@XStreamAlias("type")
private int messageType;
private String content;
@XStreamConverter(value=BooleanConverter.class, booleans={false}, strings={"yes", "no"})
private boolean important;
@XStreamConverter(SingleValueCalendarConverter.class)
private Calendar created = new GregorianCalendar();
public RendezvousMessage(int messageType, boolean important, String content) {
this.messageType = messageType;
this.important = important;
this.content = content;
}
}
Now it is possible to generate this XML:
<message type="15" important="no" created="1154097812245">This is the message content.</message>
Note, that no XStreamAsAttribute annotations were necessary. The converter assumes it implicitly.
Omitting Fields
Sometimes a class may contain elements that should not be part of the resulting XML. In our case we may now drop the 'messageType', since we are only interested at the content. This is easy using the @XStreamOmitField annotation:
@XStreamAlias("message")
class RendezvousMessage {
@XStreamOmitField
private int messageType;
@XStreamImplicit(itemFieldName="part")
private List<String> content;
@XStreamConverter(value=BooleanConverter.class, booleans={false}, strings={"yes", "no"})
private boolean important;
@XStreamConverter(SingleValueCalendarConverter.class)
private Calendar created = new GregorianCalendar();
public RendezvousMessage(int messageType, boolean important, String... content) {
this.messageType = messageType;
this.important = important;
this.content = Arrays.asList(content);
}
}
The resulting XML does not contain the type of the message anymore:
<message> <part>firstPart</part> <part>secondPart</part> <important>no</important> <created>1154097812245</created> </message>
Auto-detect Annotations
Until now we have always told you, that you have to call processAnnotation to configure the XStream instance with the present annotations in the different classes. However, this is only half the truth. You can run XStream also in a lazy mode, where it auto-detects the annotations while processing the object graph and configure the XStream instance on-the-fly:
package com.thoughtworks.xstream;
public class Tutorial {
public static void main(String[] args) {
XStream stream = new XStream();
xstream.autodetectAnnotations(true);
RendezvousMessage msg = new RendezvousMessage(15);
System.out.println(stream.toXML(msg));
}
}
The resulting XML will look as expected! Nevertheless you have to understand the implications, therefore some words of warning:
- Chicken-and-egg problem
An XStream instance caches all class types processed for annotations. Every time XStream converts an object it will in auto-detection mode first process the object's type and all the types related (as explained above). Therefore it is no problem to serialize an object graph into XML, since XStream will know of all types in advance. This is no longer true at deserialization time. XStream has to know the alias to turn it into the proper type, but it can find the annotation for the alias only if it has processed the type in advance. Therefore deserialization will fail if the type has not already been processed either by having called XStream's processAnnotations method or by already having serialized this type. However, @XStreamAlias is the only annotation that may fail in this case.
- Concurrency
XStream is not thread-safe while it is configured, thread-safety is only guaranteed during marshalling and unmarshalling. Unfortunately an annotation is defining a change in configuration that is now applied while object marshalling is processed. Therefore will the auto-detection mode turn XStream's marshalling process in a thread-unsafe operation. While XStream synchronizes the configuration modification, it cannot guard concurrent reads and you may run under certain circumstances into concurrency problems. If you abolutely have to rely on annotation processing on the fly, you will have to use separate XStream instances for each thread - either by using everytime a new instance or by a shared pool.
- Exceptions
XStream uses a well-defined exception hierarchy. Normally an InitializationException is only thrown while XStream is configured. If annotations are processed on the fly they can be thrown obviously also in a marshalling process.
- Performance
In auto-detection mode XStream will have to examine any unknown class type for annotations. This will slow down the marshalling process until all processed types have been examined once.
Please note, that any call to XStream.processAnnotations will turn off the auto-detection mode.
Summing up
The XStream annotations support might help you configuring your class mappings in some ways, as the custom configuration will appear in your types, but might not be the solution for other problems, i.e. when you need to map the same type to two different XML 'standards'. Others might claim that the configuration should be clearly stated in a Java class and not mixed with your model, its up to you to pick the best approach in your case: Annotations or direct method calls to the XStream instance. Annotations do not provide more functionality, but may improve convenience.