JAXB - Annotations, Type Adapters: XmlJavaTypeAdapter

For some Java container types JAXB has no built-in mapping to an XML structure. Also, you may want to represent Java types in a way that is entirely different from what JAXB is apt to do. Such mappings require an adapter class, written as an extension of XmlAdapter<XmlType,ApplType> from the package javax.xml.bind.annotation.adapters. The annotation XmlJavaTypeAdapter is provided for announcing the adapter in the desired place.

We'll illustrate adapters by defining a substitution of a map for an array. Here is an XML example of the data we have to deal with.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns:training xmlns:ns="http://foo/bar">
    <brochure>
        <course price="123.45" id="c1">
            <name>Course 1</name>
        </course>
        <course price="123.45" id="c0">
            <name>Course 0</name>
        </course>
    </brochure>
</ns:training>

The course elements could be represented as a list or array, but we would like to process this data in our application as a map of the id attribute to the Course object. Although JAXB is capable of handling maps, we have seen (in section Top-level Elements: XmlRootElement) that the resulting XML structure isn't as simple as possible. To achieve our goal, we write a class Brochure containing the map we have in mind and declare that this is the one that has to be adapted to something JAXB knows how to handle, i.e., the classCourses containing a simple array of Course objects.

@XmlRootElement(name="training")
public class Training {
    @XmlElement
    public Brochure brochure;
    public Training(){}
    public Training( Brochure b ){
        brochure = b;
    }
}

@XmlJavaTypeAdapter(BrochureAdapter.class)
public class Brochure {
    Map<String,Course> courses;
    public Brochure() {
        courses = new HashMap<String, Course>();
    }
}

public class Courses {
    @XmlElement(name="course")
    public Course[] carray;
}

public class Course {
    @XmlAttribute
    String id;
    @XmlElement
    String name;
    @XmlAttribute
    Price price;
}

Class Brochure is annotated with XmlJavaTypeAdapter, defining class BrochureAdapter as its adapter, and this is, of course, the interesting class. It has to override methodsunmarshal and marshal.

public class BrochureAdapter extends XmlAdapter<Courses,Brochure> {
    @Override
    public Brochure unmarshal( Courses value ){
        Brochure b = new Brochure();
        for( Course c : value.carray )
            b.courses.put( c.id, c );
        return b;
    }

    @Override
    public Courses marshal( Brochure b ){
        Courses courses = new Courses();
        Collection<Course> c = b.courses.values();
        courses.carray = c.toArray(new Course[c.size()]);
        return courses;
    }
}

Courses is a class JAXB knows how to handle with respect to XML data, and the result of JAXB's innate capabilities is passed to the adaption for unmarshalling. In this method, we convert the data to a structure according to the desired class Brochure with its map. The reverse marshalling process has to convert a Brochure object with its map to a Courses object, which is easily done by putting the map values into an array.

To summarize: XML binding happens against the class Courses, whereas application programming uses the Map type field courses in class Brochure.