bind

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

Dani Buiza

Daniel Gutierrez Diez holds a Master in Computer Science Engineering from the University of Oviedo (Spain) and a Post Grade as Specialist in Foreign Trade from the UNED (Spain). Daniel has been working for different clients and companies in several Java projects as programmer, designer, trainer, consultant and technical lead.
Subscribe
Notify of
guest

This site uses Akismet to reduce spam. Learn how your comment data is processed.

2 Comments
Oldest
Newest Most Voted
Inline Feedbacks
View all comments
Gary Mills
Gary Mills
5 years ago

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 »

John
John
10 months ago

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?

Back to top button