Chapter 15. Data Binding

15.1.1. Class Generation

The first process, class generation, provides a means to convert an XML document to Java. When data binding converts an XML document into a Java representation, it seeks to provide access to just the data in the document. Additionally, data binding provides some level of meaning to the information in the document. It does this by creating the Java representation with accessor and mutator[26] methods like getItem( ) and setTeacher( ), instead of getElement( ) and setAttribute( ). This makes dealing with documents like the one in Example 15-1 less about Java and more about business logic, which is obviously a good thing. However, these wonderfully Java classes must exist before an XML document can be turned into an instance of one, so I'm back to class generation.

[26]When I say "accessor," I'm referring to what most people call a "getter" method; when I say "mutator," I'm referring to what most people call a "setter" method. However, I also know that a "setter" is a dog, not a Java method, so I'm quick to tell my students not to use that term. Just an idiosyncrasy, I suppose!

Class generation is the process of taking a set of XML constraints and generating Java classes (and possibly interfaces) from those constraints. Think about it this way: XML constraints (like those found in a DTD or XML Schema) are equivalent to Java class definitions. They define the way that data is represented. On the other hand, an XML document is equivalent to an instance of these classes, in that it is simply a set of data that fulfills the contract defined by the document's constraints. Now, read this paragraph again, slowly, and you'll have it.

The data binding frameworks I talk about in this chapter all have a way of representing a document's constraints (usually through a DTD or an XML Schema, but there are also some other options, which I'll get to in the appropriate section). These constraints can then be run through some form of a class generation tool, and you get Java source code ready to compile. This code, once compiled, can be used to generate instance data based on an XML document. You end up with a process akin to that shown in Figure 15-1.

Figure 15-1. Class generation in XML data binding

Note that the final product here can be concrete classes, interfaces, interfaces and implementations, or any other permutation of Java classes. In the case of Example 15-1 (assuming that the constraints are represented in some arbitrary form), you might end up with a Catalog interface like this:

public interface Catalog {
    public List getItemList( );
    public void addItem(Item item);
    public void setItemList(List items);
}

Further, you might have an Item interface like this:

public interface Item {
    public String getID( );
    public void setID(String id);
    public int getLevel( );
    public void setLevel(int level);

    public String getTitle( );
    public void setTitle(String title);
    public String getTeacher( );
    public void setTeacher(String teacher);
    public List getGuests( );
    public void addGuest(String guest);
    public void setGuestList(List guests);
    public String getDescription( );
    public void setDescription( );
}

This is quite a bit more useful than writing hundreds of lines of SAX callbacks. It makes working with the document a piece of cake, instead of an exercise in your Java and XML API skills. These are just examples, and not necessarily representative of what you'll get using the APIs covered in this chapter. However, in the following sections, I'll show you exactly how to use the API and let you know what to expect.

15.1.2. Unmarshalling

Keep in mind that once you have a set of generated classes, you still don't have a great many uses for them. Sure, you could use an existing lower-level XML API to read in an XML document, pull out the data, create new instances of the generated classes, and populate them with the data from the XML. But data binding provides all this out of the box, so why bother with that? In fact, data binding frameworks provide for exactly that process. And in that context, unmarshalling is the process of converting an XML document into an instance of a Java class.

NOTE: I've seen, and even been a part of, a lot of confusion about the marshalling/unmarshalling terminology. I'm using the terminology as defined in Sun's latest version of the Java Architecture for Data Binding (JAXB) specification, which is certain to become the standardized vocabulary. In that specification, marshalling is moving from Java to XML, and unmarshalling is moving from XML to Java. I'd stick with those definitions if I were you, as well.

This turns out to be a pretty simple process; you get an XML document, pass it to some tool or class instance in your data binding framework, and you get back a Java object. This is usually a class instance of the top-level Java object representing your document. So, again using Example 15-1, you would get back an instance of the Catalog class. You'll typically need to cast from a java.lang.Object to the specific class that you're expecting, since the framework won't know anything about your classes (because they were generated). But after the class cast, you're ready to work with the object as a Catalog, not as an XML document. You can then use the various accessor and mutator methods to work with the data, and when you are ready to send the document back to the XML from whence it came, you marshal the document.

15.1.3. Marshalling

Marshalling is just the opposite of unmarshalling. It is the process of converting a Java object and its dependent objects into an XML representation. In many cases, marshalling is part of a repeated cycle of transformations to and from XML, and is paired with unmarshalling. As an example, check out Figure 15-2, which is a typical application flow.

Figure 15-2. XML data binding application flow

There are two distinct ways to marshal a Java object. The first is to invoke a marshal( ) method on an object; this method is usually generated along with the accessors and mutators during class generation. The method recursively calls the marshal( ) method on each of its dependent objects, until you end up with an XML document. Note that the target XML document does not have to be the same as the original XML; you can easily end up with a vast number of archived XML documents by supplying different filenames to the marshalling process.

A different approach to marshalling, and the one I favor, is having a standalone class that performs marshalling. Instead of invoking marshal( ) on a generated object, you invoke marshal( ) on the standalone class, and pass it the object to marshal. This is useful because it performs the same tasks as illustrated previously, but also allows classes that were not originally unmarshalled from XML to be converted to XML. Think about it this way: data binding, used like this, becomes a persistence framework. Any object with bean-like properties (setXXX( ) and getXXX( )) can easily be converted to XML! You get the power of data binding with the flexibility of persistence. This is a handy combination, and supported by some of the frameworks I talk about in this chapter.

I realize that if you're new to data binding, this may sound a bit confusing and vague; sort of like talking about chemistry. I'd much rather blow some things up (err. . . you know!), so in the rest of the chapter I show you how to use some data binding frameworks. Since I'm going to cover four of these, none of the examples are immensely complex; instead I focus on how to use the class generation, marshalling, and unmarshalling capabilities of each framework. That should be more than enough to get you going.

15.1.4. Use Cases

As a final explanation of data binding and why it's worthwhile, I will give you a small sampling of use-cases. Some of these are best suited for the lower-level APIs like SAX or DOM, and some are perfect for data binding. In Table 15-1, I've listed a common use case, the type of API that would work well, and a short reasoning behind my decision. This should help you see how data binding fits into the XML landscape.

Table 15-1. API use cases

Use case	Well-suited API	Reasoning
XML IDE	DOM or JDOM	Tree-based viewing of XML, as in an IDE, closely follows the tree-based models of DOM and JDOM.
XML messaging server	SAX	Since speed is the most important factor, SAX allows the fastest stream-based reading of messages.
Configuration data	Data binding	The content, rather than the model, is paramount. Data binding saves time and adds convenience to reading configuration data.
XML transformations	DOM or JDOM	Changing both structure and content requires modification of content (rules out SAX) and structure (rules out data binding).
XML messaging client	Data binding	When the message format is known ahead of time, the client can benefit from easy Java objects, as created by data binding.

Obviously, these are just a few common XML applications, but they should give you an idea of when to use a low-level API and when to use a higher-level one.