XML Bindings

JAXB Bindings

Java Architecture for XML Binding (JAXB) allows Java developers to map Java classes to XML representations. JAXB provides two main features: the ability to marshal Java objects into XML and the inverse, i.e. to unmarshal XML back into Java objects. In other words, JAXB allows storing and retrieving data in memory in any XML format, without the need to implement a specific set of XML loading and saving routines for the program's class structure.

iBeans support binding frameworks such as JAXB and Jackson. These frameworks use annotations to describe how data is mapped to a Java object model. For example, lets say we have an XML file that describes a person. When we receive that Xml we want to convert it into a Person object. The XML looks like this-

<person>
    <name>John Doe</name>
    <dob>01/01/1970</dob>
    <emailAddresses>
        <emailAddress>
            <type>home</type>
            <address>john.doe@gmail.com</address>
        </emailAddress>
        <emailAddress>
            <type>work</type>
            <address>jdoe@bigco.com</address>
        </emailAddress>
    </emailAddresses>
</person>

And we have an object Person we want to create from the XML. We use standard JAXB annotations to describe how to perform the mapping (The EmailAddress object is just another JavaBean with JAXB Annotations) -

@XmlRootElement(name = "person")
@XmlAccessorType(XmlAccessType.FIELD)
public class Person
{
    private String name;
    private String dob;

    @XmlElementWrapper(name = "emailAddresses")
    @XmlElement(name = "emailAddress")
    private List<EmailAddress> emailAddresses;

    public String getName()
    {
        return name;
    }

    public void setName(String name)
    {
        this.name = name;
    }

    public String getDob()
    {
        return dob;
    }

    public void setDob(String dob)
    {
        this.dob = dob;
    }

    public List<EmailAddress> getEmailAddresses()
    {
        return emailAddresses;
    }

    public void setEmailAddresses(List<EmailAddress> emailAddresses)
    {
        this.emailAddresses = emailAddresses;
    }
}

At this point iBeans can figure out whether to perform a JAXB transform based on the parameters of the method being called. For example -

@Receive(uri = "jms://people")
public void processPerson(Person person)
{
	//tickle him
}

Here we would receive the people.xml on a JMS queue, iBeans would see that Person.class is an annotated JAXB object and that we had received XML from the JMS queue and perform the conversion.

Binding transformers can also be used with iBean interfaces, for example we could parse the response from Twitter into a status object -

@Call(uri = "http://www.twitter.com/statuses/update.xml")
public Status statusesUpdate(@PayloadParam("status") String status) throws CallException;

Generated JAXB Classes

Most often JAXB classes are generated from schema and this doesn't make a difference to iBeans. In fact if Person was part of a set of generated classes, iBeans would create a JAXBContext for all the generated classes and make that context available for the transform. When creating the context it looks for either a jaxb.index file or an ObjectFactory class in the package of the annotated class. Typically the JAXB code generator will create the jaxb.index file or the ObjectFactory class for you.

Hand-rolled JAXB Classes

If you just annotate your own classes and do not create a jaxb.index or ObjectFactory class, iBeans will load just the required class into a JAXBContext for transformation.

Global JAXBContext

It is possible to define a global JAXBContext; a single context that will be used for all transforms in your application. This context will always be used instead of iBeans creating one for you. This can be useful if you need to configure specific properties on the context. To create a shared JAXBContext create a module class that creates it i.e.

public class JAXBConfigModule extends AbstractGuiceIBeansModule
{
    protected void doConfigure() throws Exception
    {
        //load annotated classes from these packages
        JAXBContext jaxb = JAXBContext.newInstance("com.foo, com.bar");
        bind(JAXBContext.class).toInstance(jaxb);
    }
}

See Using Guice for more information about modules and dependency injection.

JAXB without annotations Currently iBeans only recognises JAXB classes that have been annotated, which means binding information defined in a jaxb.xml descriptor is not discovered. This is a feature enhancement, please vote on IBEANS-153 if you need this feature.

Intercepting JAXB Transforms

So far we have discussed how iBeans will perform automatic JAXB transforms. Sometimes you may want to intercept the transform, to do this Just create a transformer with a method return or param type of your JAXB class -

@Transformer(sourceTypes = {String.class, InputStream.class})
public Person toPerson(Document doc, JAXBContext context) throws JAXBException
{
    return (Person) context.createUnmarshaller().unmarshal(doc);
}

The JAXBContext instance will either be created for you or the global context for you application will be used. One reason for doing this would be to strip out some XML elements and create objects from a subset of the XML received. For more information about transforms see the Working with Transformers section.