JAXB generates the mapping code based on the schema of the documents you’ll be processing. It creates domain classes that model the schema and creates all the code you need to read and write documents.A Working JAXB Example
First things first: download JAXB from java.sun.com, and since it relies on other XML libraries, downloading their whole XML package is perhaps the easiest way to go. As of the writing of this article, the latest pack is Summer 02. Set up the environment as per the instructions or nothing will work. The source code for the example, the schema you’ll use, and a document conforming to it are all available to download in this article.

The example document I use is Shakespeare’s “A Midsummer Night’s Dream”, which I found on the Web in XML format. I made a few small changes to slightly simplify the structure and emphasize issues I wish to focus on, and I generated a W3C Schema using the latest version of Altovira’s excellent XML Spy Enterprise. (Figure 1 shows the fairly simple schema in the XML Spy diagramming format.)

Figure 1: The Play Schema

The play schema shows that a play must contain six elements. One element is an act, which must itself contain many scenes, and scenes consist of many intermingled stage directions and speeches. Speeches contain many speakers, lines, and stage directions, again in no predictable order.

Figure 2 shows a simple play-viewer application that I put together to demonstrate the principles of processing with JAXB. Writing this would have been a lot easier had I used Tomcat and an HTML GUI, but I didn’t want to “complexify” things.

Figure 2: Play Viewer

How long would it take you to write this using SAX or DOM? The GUI is quite straight forward, but the mapping code may take you a while. Maybe two days? I did the entire thing in half a day using JAXB, and most of that was spent playing with the enigmatic Swing interface, trying to make it look a bit prettier for the screenshot. I created the mapping code in about three seconds. The panel on the left contains a standard tree and the one on the right contains a subclass of Jlabel, which I altered to implement the Scrollable interface and to hold off displaying its contents until the application gives it permission.Using the Code Generator
Start by unpacking the xml and xsd files into a development directory, which contains a directory called 'src'. Create a new directory under src called model. On the command line issue the following instruction:

  xjc ?d src ?p model play.xsd

If you’ve setup JAXB correctly you should see a message telling you that it’s parsing the schema, followed by another message saying it’s compiling the schema, and finally a list of the classes it has generated appears. Issuing the xjc command by itself produces a small help screen that explains the parameters. The options we’ve used here tell JAXB to both generate the classes into the src directory and put them in the model package.

If you have a legacy IDE like JBuilder, then you probably should generate javadocs for the classes you’ve just generated. If, like me, you use the impressive new version of IntelliJ IDEA, then this isn’t an issue. IDEA reads the javadocs directly from the source and displays them in a tool-tip window at your request.

Next, open the model package in your favorite IDE and have a look at it. Its structure is very similar to the schema on which it’s based. Where a one-to-one relationship exists, a method returns an object of the related type. For example, if you look at the Play class itself you’ll see instance methods for retrieving an instance of Title.

Where a one-to-many relationship exists, a java.util.List class is returned. For example, instances of Play have a getAct() method that returns a List containing Act objects. The code I use to get the first act of the play (in ViewPanel’s constructor) simply gets the first element of the list:

  currentAct = (Act) play.getAct().get(0); 

Of course, if I planned on outputting all of the acts in sequence I could just get an iterator from the list and use that. But I’m jumping ahead. The first thing you should do with your generated classes is use them to read an XML file. In the example, you can do this with the following three lines:

  1	JAXBContext ctx = JAXBContext.newInstance("model");  2	Unmarshaller u = ctx.createUnmarshaller();  3	play = (Play) u.unmarshal(new File("/play/data/amsnd.xml"));

The argument on the line 1 is the name of the package to which the model belongs. The filename on line 3 is the XML file to parse; you should change this to refer to your copy of the file.

In this code, play is the head of the object tree that JAXB generates. From here I can use my domain model as I please. For example, the status bar contains details of the currently selected act and scene. Upon initialization, I use the following code to gather that information:

  1  Act initialAct = (Act) Model.getPlay().getAct().get(0);  2  Scene initialScene = (Scene) initialAct.getScene().get(0);

The Model class is a singleton I’ve written to return the root of the domain object tree. Act and Scene are classes JAXB generates. Multiple objects, in this case acts and scenes, are stored in Lists. For the initial status bar display, I’m interested only in the first of each of these, so I can access the first element directly.

In our play schema, both act and scene have an attribute called title. JAXB translates XML attributes to object attributes. So, our Act and Scene classes have getTitle() methods that return String.

Look at the Line schema element. Notice it has no attributes, but its contents are the text for the line. Treat values like this as unnamed attributes, and access them with the getValue() method.

Building and Running
When you’re building or running an application that uses JAXB, you’ll need to include the following three libraries, which Sun distributes with JAXB:

You’ll also need an XML parser. If you’re using the 1.4.1 or later SDK, then you’ll already have one. If not, Xerces from the Apache XML project (xml.apache.org) is a fairly useful and common one.Customization Through the Schema
Sometimes the code generated from the schema won’t meet your exact requirements. Sometimes the schema has defects in it. Sometimes you just want to play around with things. In all of these cases, you can affect the behavior of the code generator through customization. At the moment, the reference implementation (RI) implements customization directly through the schema being processed, but the specification says that external customization scripts eventually will be supported too.

Customizing the schema won’t affect the schema itself, except when it’s being processed by xjc because it’s done through a set of schema extension points. The spec allows for many customization points, at many levels of generation. This article doesn’t have room for a detailed examination of these or a detailed explanation of schema extensions, but for a sample I’ll show how to generate Vectors rather than Lists.

A schema extension is basically detail you add to the schema to give instructions and extra information to specific processors. In this case, the extensions are aimed at xjc and all other processors should ignore them.

I’m adding a global customization, which means that it affects all generated code. While this is a simple customization to make, quite a few other more complex ones provide real power to JAXB.

Here are the changes you must make to the schema to make JAXB generate java.util.Vector rather than List, its default collection (note that the top-level schema tag needs to be changed too):

                                ...

Without going into too much detail about schemas, the annotation tag introduces a part of the schema that is usually intended for schema processing software. The appinfo tag introduces instructions for a particular processing application (in this case, JAXB’s xjc code-generation tool). Usually, each application uses its own namespace, as JAXB has done here.

As it happens, simply changing the default collection type from List to Vector has no effect at all on the sample application I’ve presented here. My code works by retrieving iterators from collections, not the collections themselves. So when I generate the new model from this change, my code works without any new faults.

Some people are leery of altering their schemas. The standard supports external annotations, but the current implementation doesn’t. This is something that will be rectified in the future.

You’re on Your Way
That’s all you need to know for a basic introduction to JAXB. Currently, the RI is in beta, but a final version is expected to be released around mid-February?so you don’t have long to wait. The full release isn’t going to differ much from the beta (apart from bug fixes), so you can start developing immediately against the beta fairly safely and then change over to the official first version when it’s released.

If you decide to use JAXB technology, read the specification document from Sun, and pay particular attention to the section on customization. The customization I’ve introduced here really is trivial. JAXB is capable of considerably more.