This page provides a series of examples illustrating how a class can be annotated. It acts as a quick and dirty overview of how the framework can be used and also acts as a reference page. All examples can be downloaded for convenience. For further information take a look at the Tutorial.
1 Creating nested path elements
Here an example of how to use the Path annotation to create nested elements and attributes using a single annotated class. Below is an example showing two elements nested within a XPath expression.
@Root
public class Example {
@Path("a/b[1]")
@Element
private String x;
@Path("a/b[2]")
@Element
private String y;
}
The below snippet shows an example of the resulting XML that can be generated by this class.
<example>
<a>
<b>
<x>foo</x>
</b>
<b>
<y>bar</y>
</b>
</a>
</example>
This example can be downloaded from here.
2 Dynamically selecting an element name
Here an example of how to use the ElementUnion annotation to specify a list of options to use for serialization. The union annotation pairs an element name with a type, this allows the element name to dictate selection of the type deserialized and also allows a known type to be serialized with a specific element name.
@Root
public class Example {
@ElementUnion({
@Element(name="text", type=String.class),
@Element(name="int", type=Integer.class),
@Element(name="double", type=Double.class)
})
private Object value;
}
The below snippet shows an example of the resulting XML, here because the object value was an integer the resulting XML element is called int.
<example> <int>12</int> </example>
This example can be downloaded from here.
3 Constructor injection
Constructor injection can be performed with any number of arguments using any of the XML annotations. In this example the Element annotation is used to identify two values to be injected in to a specific constructor.
@Root
public class Point {
@Element
private final int x;
@Element
private final int y;
public Point(@Element(name="x") int x, @Element(name="y") int y) {
this.x = x;
this.y = y;
}
}
The below snippet shows an example of the resulting XML, both the x and y values will be injected in to the annotated constructor.
<point> <x>10</x> <y>4</y> </point>
This example can be downloaded from here.
4 Constructor injection with nested path elements
In this example constructor injection is performed on two elements which also have Path annotations. As can be seen if there is no ambiguity there is no need to specify the path annotations on the constructor. This reduces the clutter that can occur with excessive annotations.
@Root
public class Point {
@Path("a/b[1]")
@Element
private final int x;
@Path("a/b[1]")
@Element
private final int y;
public Point(@Element(name="x") int x, @Element(name="y") int y) {
this.x = x;
this.y = y;
}
}
The below snippet shows an example of the resulting XML, both the x and y values will be injected in to the annotated constructor.
<point>
<a>
<b>
<x>2</x>
<y>7</y>
</b>
</a>
</point>
This example can be downloaded from here.
5 Using namespaces
Below is an example of how to use namespaces with the Namespace annotation. Here two namespaces are declared without a prefix, this means they belong to the default namespace.
@Root
public class Example {
@Namespace(reference="http://www.blah.com/ns/a")
@Element
private String a;
@Namespace(reference="http://www.blah.com/ns/b")
@Element
private String b;
}
The below snippet shows an example of the resulting XML, as can be seen the namespaces are used to qualify the resulting elements.
<example> <a xmlns="http://www.blah.com/ns/a">foo</a> <b xmlns="http://www.blah.com/ns/b">bar</b> </example>
This example can be downloaded from here.
6 Declaring a namespace prefix
When using the Namespace annotation a prefix can be specified. This prefix is added to the qualified XML elements to ensure they are within a specific namespace, rather than the default namespace.
@Root
public class Example {
@Namespace(prefix="ns1", reference="http://www.blah.com/ns/a")
@Element
private String a;
@Namespace(prefix="ns2", reference="http://www.blah.com/ns/b")
@Element
private String b;
}
The resulting XML shows that both elements contain the namespace prefix declared in the annotation.
<example> <ns1:a xmlns:ns1="http://www.blah.com/ns/a">foo</ns1:a> <ns2:b xmlns:ns2="http://www.blah.com/ns/b">bar</ns2:b> </example>
This example can be downloaded from here.
7 Namespace prefix inheritance
Here a class level namespace is declared using the Namespace annotation. The element declared with the same namespace reference does not need to declare a prefix as it will be inherited from the class level annotation.
@Root
@Namespace(prefix="ns1", reference="http://www.blah.com/ns/a")
public class Example {
@Namespace(reference="http://www.blah.com/ns/a")
@Path("a/b")
@Element
private String x;
}
As can be seen in the resulting XML the namespace is declared only once, the child element inherits the original prefix reducing the verbosity of the XML.
<example xmlns:ns1="http://www.blah.com/ns/a">
<a>
<b>
<ns1:x>blah</ns1:x>
</b>
</a>
</example>
This example can be downloaded from here.
8 Default serialization
This example shows how the Default annotation can be used. When this annotation is used fields will be serialized without the need for annotations.
@Default
public class Example {
private List<Double> a;
private String b;
private String c;
private Date d;
}
As can be seen in the resulting XML is generated for all fields within the class.
<example>
<a>
<double>1.2</double>
<double>31.6</double>
<double>52.99</double>
</a>
<b>foo</b>
<c>bar</c>
<d>2012-05-22</d>
</example>
This example can be downloaded from here.
9 Default serialization of properties
This example shows how the Default annotation can be configured to use bean methods instead of fields for serialization. When used in this manner all methods that follow the Java Bean naming conventions will be considered for serialization.
@Default(DefaultType.PROPERTY)
public class Example {
private String name;
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
}
As can be seen in the resulting XML is generated for the Java Bean method.
<example> <name>John Doe</name> </example>
This example can be downloaded from here.
10 Collecting various types in a single list
Here an example of how to use the ElementListUnion can be seen. This annotation allows a number of types to be declared to match a single list, all elements that match the declared names will be gathered in to the list.
@Root
public class Example {
@ElementListUnion({
@ElementList(entry="int", type=Integer.class, inline=true),
@ElementList(entry="date", type=Date.class, inline=true),
@ElementList(entry="text", type=String.class, inline=true)
})
private List<Object> list;
}
The below snippet shows an example of the resulting XML, each type is given a name according to its type.
<example> <int>12</int> <date>2012-22-05</date> <date>1977-18-11</date> <text>blah</text> <int>1</int> <int>34525</int> <date>2001-01-05</date> </example>
This example can be downloaded from here.
11 Dynamically matching a constructor
Here an example of how to use the ElementUnion to dynamically select a constructor based on the value deserialized. Constructor matching will be done by examining the declared name and the instance type.
@Root
public class Example {
@ElementUnion({
@Element(name="int", type=Integer.class),
@Element(name="date", type=Date.class),
@Element(name="text", type=String.class)
})
private Object value;
public Example(@Element(name="int") int value) {
this.value = value;
}
public Example(@Element(name="date") Date value) {
this.value = value;
}
public Example(@Element(name="text") String value) {
this.value = value;
}
}
The below snippet shows an example of the resulting XML, here the constructor accepting a date will be invoked as that is what is deserialized from the file.
<example> <date>2001-01-05</date> </example>
This example can be downloaded from here.