Java & XML Data Binding

Chapter 1. Introduction

With the wealth of interest in XML in the last few years, developers have begun to crave more than the introductory books on XML and Java that are currently available. While a chapter or two on SAX, some basic information on JAXP, and a section on web services was sufficient when these APIs were developed, programmers now want more. Specifically, there is a huge amount of interest in XML data binding, a new set of APIs that allows XML to be dealt with in Java simply and intuitively, without worrying about brackets and syntactical issues. The result is a need in the developer community for an extensive, technically focused documentation set on using data binding; examples are no longer just helpful, but a critical, required part of this documentation set. This book will provide that technical documentation, ready for immediate use in your application programming.

To fill this need, I want to start off on the right foot and dive into some technical material. This chapter will give you basic information about existing XML APIs and how they relate to XML data binding. From there, I move on to the four basic facets of data binding, which the first half of this book focuses on. Finally, to get you ready for the extensive examples I walk you through, I devote the last portion of this chapter to the APIs, projects, and tools you’ll need throughout the rest of the book. From there on, I assault you with examples and technical details, so I hope you’re ready.

Low-Level APIs

By the simple fact that you’ve picked up this book, I assume that you are interested in working with XML from within your Java programs and applications. However, it’s probably not too smart to assume that you’re a Java and XML expert (yet—although picking up my Java and XML book could help!), so I want to take you through the application programming interfaces (APIs) available for working with XML from Java. I’ll start by detailing what I will henceforth refer to as low-level APIs. These APIs allow you direct access to an XML document’s data, as well as its structure.

To illustrate this concept a little more clearly, consider the following simple XML document:

<?xml version="1.0"?>
  
<songs>
  <song>
    <title>The Finishing Touch</title>
    <artist type="Band">Sound Doctrine</artist>
  </song>
  
  <song>
    <title>Change Your World</title>
    <artist type="Solo">Eric Clapton</artist>
    <artist type="Solo">Babyface</artist>
  </song>
  
  <song>
    <title>The Chasing Song</title>
    <artist type="Band">Andy Peterson</artist>
  </song>
</songs>

An Abridged Dictionary

Before going further, you should know a couple of terms. For those of you familiar with XML, this should be old hat, but for XML newbies, this should prevent future confusion.

Well formed

An XML document that follows all the rules of XML syntax, such as closing every open element in the correct order.

Valid

An XML document that follows the constraints set out for it by a DTD or XML Schema. If the document does not follow these constraints, it is invalid.

Anything else that confuses you can be found in a quick page, either through O’Reilly’s Learning XML, by Erik Ray, or XML in a Nutshell, by Elliotte Rusty Harold and W. Scott Means. I recommend having one or both nearby as you go through this book.

Using a low-level API, you could access the textual content of the second artist element in the second song. That’s the data of the document. In addition, a low-level API lets you change the name of the third song element to folkSong, or move the second song element before the first one. In other words, you have direct access, though methods like setName() and getChild(), to the document itself. These actions don’t involve the data in the document, but the structure. Understanding this concept is important because you’ll see in a moment that a whole set of APIs don’t allow this access and are aimed at a very different set of use cases.

In general, using a low-level API is a little more complex than using high-level APIs (discussed in a moment), as it requires more XML knowledge. Since you have access to a document’s structure, it’s not too hard to create an invalid document. Additionally, you are going to spend as much, if not more, time dealing with document structure and rules of XML than with the actual data. This means that in a typical application, you’re spending more time thinking about structure than solving any given business problem. For these reasons, low-level APIs are usually most common in infrastructure tasks or when setting up communication in messaging. When it comes to solving a specific business problem, higher-level APIs (see the next section) are often more appropriate. With that in mind, let me give you the rundown on the major low-level APIs that are currently available.

Streamed Data

The grandfather of all Java-based low-level APIs is the Simple API for XML (SAX). SAX was the first major API released that has any sort of following, and it remains the basic building block of pretty much all other APIs. SAX is based on a streaming input and reads information from an XML input source piece by piece. In other words, information is sent to the SAX interfaces as the related input stream (or reader) gets it. To use SAX for parsing, you register various handler implementations for handling content, errors, entities, and so forth. Each interface is made up of several callback methods, which receive information about specific data being sent to the parser, such as character data, the start of an element and the end of a prefix mapping. Your SAX-based application can then use that information to perform business tasks within the callback method implementations.

The advantage to this stream-based approach is raw, blazing speed. SAX easily outstrips any other API in performance (and don’t let anyone tell you differently). Because it reads a document piece by piece, making that data available as soon as it is encountered, your applications don’t have to wait for the complete document to be parsed to operate upon the data. However, that speed carries a price: complexity. SAX is probably the hardest API for developers to wrap their heads around, and even then, many have trouble writing efficient SAX code. Because data is read in a streaming fashion, your callback methods won’t have access to an element’s children, its parent, or its siblings. Instead, you have to build up some in-memory stack if you want to keep an idea of tree location. Because of this complexity, it’s easy to ignore important data or make mistakes when reading in data. As a result of this complexity, many developers pass up SAX and prefer an API that provides an in-memory model of an XML document. You can learn more about SAX online at http://www.saxproject.org.

Modeled Data

Java and XML APIs that model XML data are generally more popular, as their learning curve is much smaller. The oldest and most popular of these is the Document Object Model (DOM). This API was developed by the World Wide Web Consortium and provides a complete in-memory model of an XML document. DOM is not a parser (and neither is SAX); it requires an XML parser that supplies a DOM implementation to operate. When the parser completes its reading of an XML document, the result is a DOM tree. This tree models an XML document, with parent elements having children, textual nodes, comments, and other XML constructs. You can easily walk up and down a DOM tree using the DOM API and generally move around easily. Because you have to wait on a complete parse before using a DOM, it is often slower than using SAX; because it creates objects for each XML structure, it takes a lot more memory to operate. However, these disadvantages are paired with a significantly easier programming model, a means to traverse the content of the DOM tree, and several implementations that offer various options. For example, Apache Xerces offers a “deferred DOM,” which makes some trade-offs to reduce the memory overhead when using DOM. For more on DOM, check out http://www.w3.org/DOM.

Recently, developers have moved away from DOM. This is because DOM has some quirks that are not familiar to Java developers; this isn’t surprising, considering that DOM is specifically built to work across multiple languages (Java, C, and JavaScript). As a result, some of the choices made, such as the lack of support for Java Collections, don’t sit well with Java developers. The result has been two APIs that both are object models aimed squarely at Java and XML developers. The first, JDOM (http://www.jdom.org), is focused on simplicity and avoiding interfaces in programming. The second, dom4j (http://www.dom4j.org), keeps the DOM-style interfaces, but (like JDOM) incorporates Java collections and other Java-style features. I prefer JDOM, but then I cofounded it, so I’m a bit biased! In any case, DOM, JDOM, and dom4j all offer more user-friendly approaches to XML than does SAX, at the expense of memory and performance.

Abstracted Data

Completing the run through low-level APIs, the third model is what I refer to as abstracted data. This type of API is represented by Sun’s Java API for XML Parsing (JAXP). It doesn’t offer new functionality over the streamed data (SAX) or modeled data (DOM and company), but abstracts these APIs and makes them vendor-neutral. Because SAX and DOM are based on Java interfaces, different vendors provide implementations of them. These implementations often result in code that relies on a specific vendor parsing class, which ruins any chance of code portability. JAXP offers abstractions of the DOM and SAX APIs, allowing you to easily change parser vendors and API implementations.

The latest version of JAXP, 1.1, offers this same abstracted data model over XML transformations, but that’s a little beyond the scope of this book. In terms of pros and cons in using JAXP, I’d recommend it if you will work with SAX or DOM and can get the latest version of JAXP. It helps you avoid the hard-coded sort of problems that can creep in when working directly with a vendor’s implementation classes. In any case, this brief little whirlwind tour should give you at least a basic understanding of the available low-level Java and XML APIs. With these APIs in mind, let me move up the rung a bit to high-level APIs.