Hidden gems of functionality - JAXB

matt_steiner · ‎04-27-2010

Introduction

Ever since I got to know the charming side of JAXB (Java Architecture for XML Binding) I wanted to blog about it as I feel that this easy-to-use technique of converting Java Beans into XML (and back) should be considered as a swiss knife to be known by every serious Java Enterprise Edition developer. Unfortunately it seems as this functionality is not really documented at all within the NetWeaver Developer Studio and due to all the MDA hype people tend to forget that NW CE is based on a full-blown Java 5 EE Web Application Server (which is already a power-house by itself!)
Consequently, I decided to dash out my 2nd installment of my "Hidden Gems" series...

The Basics

As always I'll just briefly summarize the key concepts and refer you to other web sites for a more detailed information of the basics. In a nutshell, JAXB allows you to convert a Java Bean into its XML expression, which is called marshaling, and to instantiate Java Bean (hierarchies) from XML - unmarshaling. For this purpose JAXB provides two classes:

```
javax.xml.bind.Marshaller
```
```
javax.xml.bind.Unmarshaller
```

A set of Java annotations [3] in the classes is used to derive all required information about this conversion such as an objetc's associations and attributes and the datatypes involved. But that much about theorie... let's use a simple example and have a look on source code of a simple JAXB utility class:

Listing 1 - JAXBUtils

Pretty much self-explanatory right? So, there are only a few additional things to mention before you go ahead to get your hands dirty with this

@XmlRootElement

In order for JAXB to work you need a root node for the XML content. You can declare a POJO to be a root object by annotating the class with @XmlRootElement annotation. While that is straight forward for some objects like service operation request structures (modeled adhering to Enterprise Service conventions, see [4] ) it may not be possible to do with objects or DTOs you may re-use as nested entities in various places. A ~~simple~~ elegant way of overcoming that challenge is to simply introduce a container object (e.g. called RootElement), which is annotated accordingly as shown in listing 2.

Listing 2 - RootElement

If you're using the Composite Application Framwork (CAF) to model your business objects (BOs) all the generated structures are already annoated with XML declarations by default - yet, none of it is flagged explicitly as a @XmlRootElement (and you do't want to touch the generated coding by all means!) So, in order to use CAF BOs in conjunction with JAXB, you may just adopt the approach I just outlined.

ObjectFactory

The ObjectFactories (there can be multiple) are in charge of instantiating the Java Beans based on the classnames derifed from the namespaces defined in the XML content and the XML annotations. This is illustrated in listing 3.

Listing 3 - ObjectFactory

Note: You can also use a specific class called jaxb.index which may contain names of JavaBeans with a no-argument constructor and which reside in the same package as the jaxb.index file. This may just be an option for the RootElement we already talked about. (For more details about the jaxb.index file please consult the JavaDoc of the JAXBContext class [5])

The JAXB path

As shown in listing 1, we need to pass a path parameter containing a colon (!) - separated list of all package names that point to packages that include an ObjectFactory as shown in listing 4.

Listing 4 - Usage of JAXB

To better illustrate how the JAXB path maps to the corresponding package structure I have illustrated the packagaging of the Java Beans used in the above example in Figure 1. For the first token of the JAXB path "com.sap.demo.common.model" JAXB would fin dthe ObjectFactory, while for the second token "com.sap.demo.common.xml" it would find the jaxb.index file in order to instantiate the RootElement as a gerenic and reusable @XmlRootElement. So, depending on how you structure your project you may need multiple ObjectFactories as stated earlier.

Figure 1 - Package overview

Summary

Yeap... that's all there's to it. Simple, but effective. Please note that I just described one of many ways to leverage JAXB and the API is much more powerful than I was able to highlight with that blog post. In fact, I was aiming to give you the most "bang for the buck" by showing an easy way on how to use JAXB effectively (especially if you're working with CAF.)

Obviously the use cases are many-fold... my personal favorite is to model query service interfaces and use JAXB to store the serialized XML content them as CLOBs in the database. In fact, we have built an entire DisplayVariant framework as seen everyday in Object Worklist (OWL) UI patterns using the outlined scenario. But that's another blog or article by its own right - so STAY TUNED!