Jackson: not just for JSON, Smile or BSON any more -- Now With XML, too!
(NOTE: see the newer article on "Jackson 2.0 with XML")
One of first significant new Jackson extension projects (result of Jackson 1.7 release which made it much easier to provide modular extensions) is jackson-xml-databind, hosted at GitHub. Although this extension is still in its pre-1.0 development phase, the latest released version is fully usable as is and is even in some limited production use by some brave developers (running on Google AppEngine, of all things!).
So it is probably a good idea to now give a brief overview of what this project is all about.
1. What is jackson-xml-databind?
Jackson-xml-databind comes in a small package (jar is only about 55 kB) , and is used with Jackson data binding functionality (jackson-mapper jar). It provides basic replacement for JsonFactory, JsonParser and JsonGenerator components of Jackson Streaming API, and allows reading and writing of XML instead of JSON, in context of generic Jackson data binding functionality. In addition, core ObjectMapper is also sub-classed to provide customized versions of couple of other provider types, so typically all usage is done by creating com.fasterxml.jackson.xml.XmlMapper instead of ObjectMapper, and using it for data binding.
2. What is it used for?
This package is used to read XML and convert it to POJOs, as well as to write POJOs as XML. In this respect it is very similar to JAXB (javax.xml.bind) package; and an alternative for many other Java XML data binding packages such as XStream and JibX. Given Jackson support for JAXB annotations, it can be especially conveniently used as a JAXB replacement in many cases.
Functionality supported is in some ways a subset of JAXB, and in other ways a superset: XML-specific functionality is more limited (no explicit support for XML Schema), but general data binding functionality is arguably more powerful (since it is full set of Jackson functionality).
Two obvious benefits of this package compared to JAXB or other existing XML data binding solutions (like XStream) are superior performance -- with fast Stax XML parser, this is likely the fastest data binding solution on Java platform (see jvm-serializers for results) -- and extensive and customizable data POJO conversion functionality, using all existing Jackson annotations and configuration options. The main downside currently is potential immaturity of the package; however, this only applies to interaction between mature XML packages (stax implementation) and Jackson data binder (which is also fairly mature at this point).
3. So how do I use it?
If you know how to use Jackson with JSON, you know almost everything you need to use this package. The only other thing you need to know is that there has to be a Stax XML parser/generator implementation available. While JDK 1.6 provides one implementation, your best best is using something bit more efficient, such as Woodstox or Aalto. Both should work fine; Aalto is faster of two, but Woodstox is a more mature choice. So you will probably want to include one of these Stax implementations when using jackson-xml-databind.
Other than this, all you need to do is to construct XmlMapper:
XmlMapper mapper = new XmlMapper(); // can also specify XmlFactory to use, to override Stax factories used
and use it like you would any other ObjectMapper, like so:
User user = new User(); // from Jackson-in-five-minutes sample
String xml = mapper.writeValueAsString(user);
and what you would get is something like:
<User>
<name>
<first>Joe</first>
<last>Sixpack</last>
</name>
<verified>true</verified>
<gender>MALE</gender>
<userImage>AQIDBAU=</userImage>
</User>
which is equivalent of JSON serialization that would look like:
{
"name":{
"first":"Joe",
"last":"Sixpack"
},
"verified":true,
"gender":"MALE",
"userImage":"AQIDBAU="
}
Pretty neat eh?
Oh, and reverse direction obviously works similarly:
User user = mapper.readValue(xml, User.class);
There is really nothing extra-ordinary in it usage; just another way to use Jackson for slicing and dicing your POJOs.
4. Limitations
While existing version works pretty well in general, there are some limitations. These mostly stem from the basic difference between XML and JSON logical models; and specifically affect handling of Lists/arrays. XmlMapper for example only allows so-called "wrapped" lists (for now); meaning that there is one wrapper XML element for each List or array property, and separate element for each List item.
Compared to JAXB (and related to JAXB annotation support), no DOM support is included; meaning, it is not possible to use converters that take or produce DOM Elements.
With respect to Jackson functionality, while polymorphic type information does work, some combinations of settings may not work as expected.
And given project's pre-1.0 status, testing is not yet as complete as it needs to be, so other rough edges may also be found. But with help of user community I am sure we can polish these up pretty quickly.
5. Feedback time!
So what is needed most at this point? Users, usage, and resulting bug (or, possibly, success) reports! Seriously, more usage there is, faster we can get the project up to 1.0 release.
Happy hacking!
