JAXB unmarshal example
In my last article, I’ve explained how to marshall java objects to xml using JAXB. In this one, we are going to see how to do the complementary operation: unmarshal xml files into java objects and what should be taken into consideration while doing this operation.
For this purpose we are going to use the same example as in the marshal example article. We are going to unmarshall an xml containing information about a list of museums with its main exhibitions and artists exposed.
The java version used for these examples is the JRE 1.8.0. The IDE used is Eclipse SDK Version: Luna (4.4) but the code should work in any other IDE supporting java.
The code shown bellow unmarshalls a given xml file into java objects. The classes of these objects should contain a set of attributes and annotations:
XML file:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <MUSEUMS> <MUSEUM children_allowed="false"> <MUSEUM_NAME>Reina Sofia Museum</MUSEUM_NAME> <CITY>Madrid</CITY> <PERMANENT_EXHIBITION> <NAME>Permanent Exhibition - Reina Sofia Museum</NAME> <ARTIST>Picasso</ARTIST> <ARTIST>Dali</ARTIST> <ARTIST>Miro</ARTIST> <FROM>1900-01-01</FROM> <TO>2014-12-31</TO> </PERMANENT_EXHIBITION> </MUSEUM> <MUSEUM> <MUSEUM_NAME>Louvre Museum</MUSEUM_NAME> <CITY>Paris</CITY> <PERMANENT_EXHIBITION> <NAME>Permanent Exhibition - Louvre Museum</NAME> <ARTIST>Leonardo da Vinci</ARTIST> <ARTIST>Caravaggio</ARTIST> <ARTIST>Delacroix</ARTIST> </PERMANENT_EXHIBITION> </MUSEUM> </MUSEUMS>
and the Java main program:
File file = new File("museums.xml"); JAXBContext jaxbContext = JAXBContext.newInstance(Museums.class); Unmarshaller jaxbUnmarshaller = jaxbContext.createUnmarshaller(); Museums museums = (Museums) jaxbUnmarshaller.unmarshal(file); System.out.println(museums);
The output produced would be something like:
Name: Prado Museum City: Madrid Permanent Exhibition - Prado Museum Game of Bowls (1908), by Henri Matisse Name: Reina Sofia Museum City: Madrid ATTENTION! Children are not allowed in this museum Permanent Exhibition - Reina Sofia Museum Name: British Museum City: London Permanent Exhibition - British Museum Name: MOMA City: New York Permanent Exhibition - MOMA Name: Louvre Museum City: Paris Permanent Exhibition - Louvre Museum
but this depends in the current Java code handling the Museums
class.
The method createUnmarshaller
of the class JAXBContext
creates an instance of the type Unmarshaller
that allows us to proceed with our tasks. If the class Museums
and its members are properly configured using the right JAXB annotations and field members, everything should work fine.
The museums class contains a list of Museum items:
@XmlRootElement( name = "MUSEUMS" ) public class Museums { List museums; /** * element that is going to be marshaled in the xml */ @XmlElement( name = "MUSEUM" ) public void setMuseums( List museums ) { this.museums = museums; } ...
and the Museum class contains fields that can be XML elements like the name or the city or XML attributes like the children allowance. These fields can be of any JAXB supported type:
@XmlType( propOrder = { "name", "city", "permanent", "special" } ) @XmlRootElement( name = "MUSEUM" ) public class Museum { String name; @XmlElement( name = "MUSEUM_NAME" ) public void setName( String name ) { this.name = name; } Boolean childrenAllowed; @XmlAttribute( name = "children_allowed") public void setChildrenAllowed( Boolean childrenAllowed ) { this.childrenAllowed = childrenAllowed; } Exhibition special; @XmlElement( name = "SPECIAL_EXHIBITION" ) public void setSpecial( Exhibition special ) { this.special = special; } ...
In case we want to use a field of a non supported type we have to implement ourselves an Adapter that indicates JAXB how to manage this kind of objects. This adapter extends the XmlAdapter
class and implements its marshal
and unmarshal
methods:
public class LocalDateAdapter extends XmlAdapter { public LocalDate unmarshal( String v ) throws Exception { return LocalDate.parse( v ); } public String marshal( LocalDate v ) throws Exception { return v.toString(); } }
This adapter is used in the following way:
@XmlJavaTypeAdapter( LocalDateAdapter.class ) @XmlElement( name = "FROM" ) public void setFrom( LocalDate from ) { this.from = from; }
Main annotations used
We are going to see some important points related to the configuration of the used classes and the annotations used to configure JAXB:
@XmlRootElement
: This annotation binds an XML node with a class or an enum. In our example we bind, using the @XmlRootElement
, the XML element <MUSEUMS>…</MUSEUMS> with the class Museums by annotating this class with @XmlRootElement( name = "MUSEUMS" )
.
For more information about this annotation please refer to XMLRootElement
@XmlElement
: Maps XML node into a non static field of a class. In our example, among others, we map the element <MUSEUM_NAME>Prado Museum</MUSEUM_NAME> with the field name of the class Museum
using the annotation @XmlElement( name = "MUSEUM_NAME" )
in the setName()
method.
For more information about this one, please refer to XMLElement.
@XmlAttribute
: This annotation maps an XML attribute with a non static field of a class. We bind the childrenAllowed field of the Museum class with the xml attribute <MUSEUM children_allowed=”false”> using the following code:
@XmlAttribute( name = "children_allowed" ) public void setChildrenAllowed( Boolean childrenAllowed ) { this.childrenAllowed = childrenAllowed; }
For more information about the annotation @XmlAttribute
go to XMLAttribute.
And this is how we can unmarshal an XML file into Java objects.
JAXB offers several ways to marshal and un marshal collections. In our example, we just created a Museums class that contains a list of Museum items, so JAXB can manage directly this class by simply using the annotations explained above. It is also possible to achieve something similar by using the annotations @XmlElementWrapper
or @XmlList
, but under my point of view, these ones are more complicated, offer less options and ties you in several ways in your class modelling.
As already mentioned in the article, it is also possible to generate java classes with JAXB annotations automatically by using XSD (XML Schmema Definition). This offers also the possibility to validate the XML files against the provided XML Schema that we want to unmarshall. It is also important to mention that JAXB does not need an XSD to work (as we saw in this example), this offers Java programmers a lot of flexibility.
All the code explained in this article and some running examples can be found in the following link: unmarshall.zip
Hello Dani Buiza, thank you so much for this post. it is helping me alot. I’m new to JAXB and XML unmarshalling. your post is the most straight forward to follow. I’m still struggling tho trying to decipher or decode I’m strugging with how to break an xml message down to get what is needed from it. I hope you can help me. thanks in advance. I don’t know if I should create a class for each block/section and how to get the attributes from fields with attributes. below is a sample of the messages I’m looking at decoding I’m… Read more »
How does the main java program above know where to find the museums.class? Can you give an example of your directory structure and the import statements needed by the main class?