Annotated JAXB Classes

Over the last week or so, I've started to use JAXB along with the Restlet framework. We are actively developing RESTful web services here at Overstock.com. So being new to the Restlet framework, I was eager to get started. One type of representation supported by Restlet is of course XML. To generate XML representations we are using JAXB 2. Being an advocate of annotations, I thought I'd start with annotated POJO's and let the JAXB provider do the rest (I assumed this would be a lot like JPA). I ran into a problem however, trying to create a JAXBContext for my package, I got this error:

WARNING: Problem creating Marshaller
javax.xml.bind.JAXBException: "com.overstock" doesnt contain ObjectFactory.class or jaxb.index

It took me a while to figure out what went wrong. So now that I've got things working correctly, I thought I'd post this example and solution to hopefully save you some time. Given this class:

 package com.overstock;

 import javax.xml.bind.annotation.XmlAccessType;
 import javax.xml.bind.annotation.XmlAccessorType;
 import javax.xml.bind.annotation.XmlElement;
 import javax.xml.bind.annotation.XmlRootElement;

 @XmlRootElement(name="example", namespace="http://overstock.com/example")
 @XmlAccessorType(XmlAccessType.FIELD)
 public class ExampleJaxbClass {

   @XmlElement(required=true)
   private String elementOne;
   private String elementTwo;

   protected ExampleJaxbClass() {
     super();
   }

   public String getElementOne() {
     return elementOne;
   }
   public void setElementOne(String elementOne) {
     this.elementOne = elementOne;
   }
   public String getElementTwo() {
     return elementTwo;
   }
   public void setElementTwo(String elementTwo) {
     this.elementTwo = elementTwo;
   }
 }

You can easily convert it to XML via the javax.xml.bind.Marshaller class, like this:

 public class ExampleTest {

   @Test
   public void generateXml() throws JAXBException {
     ExampleJaxbClass ex = new ExampleJaxbClass();
     ex.setElementOne("first Element Value");
     ex.setElementTwo("second Element Value");

     // Get a JAXB Context for the object we created above
     JAXBContext context = JAXBContext.newInstance(ex.getClass());

     // To convert ex to XML, I need a JAXB Marshaller
     Marshaller marshaller = context.createMarshaller();

     // Make the output pretty
     marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, true);
     StringWriter sw = new StringWriter();

     // marshall the object to XML
     marshaller.marshal(ex, sw);

     // print it out for this example
     System.out.println(sw.toString());
   }
 }

Here is the XML generated by the annotations above:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:example xmlns:ns2="http://overstock.com/example">
<elementOne>first Element Value</elementOne>
<elementTwo>second Element Value</elementTwo>
</ns2:example>

Now for the problem. To create a marshaller, you first need to create a JAXBContext via its newInstance() factory method. You can create a context for a specific JAXB class, as in the example above, or you can create a context for a list of packages (check out the javadoc page for more). When using the Restlet class JaxbRepresentation (only available in Restlet 1.1m1), it uses the package version of newInstance(), that's when I got my error above. I didn't want to create an ObjectFactory (apparently this is another way to get around the above error), at least not yet if I could help it, so I wanted to get some more info on the jaxb.index file. I couldn't find out much, I even looked at the JSR-222 spec. Well, it turns out that all you need to do is add class names to the file and place the file in the package (directory) where your JAXB annotated classes reside (it's similar in one way to a jpa persistence.xml file but without the xml). Here is the content of my jaxb.index file for the example class above:

ExampleJaxbClass

As you can see, its just the class name, not the fully qualified name (the package name is determined by the directory you placed the file in) or the .class name. If you want to test this out, we need to slightly change the test above. Modify line 10 in the unit test above to look like this:

JAXBContext context = JAXBContext.newInstance(ex.getClass().getPackage().getName());

If the package com.overstock does not have jaxb.index file, this change will cause the test to throw the JAXBException. Add the file and everything works great. If you know where there is good documentation on this let me know I couldn't find any :-)

Code formatting courtesy of Code2HTML.