Creating, Appending, and Inserting

Fixing the problem I just described often leads to another problem. A common error I've seen is when developers remember to import a node, and then forget to append it! In other words, code crops up looking like this:

Element otherDocElement = otherDoc.getDocumentElement( ); Element thisDocElement = thisDoc.getDocumentElement( ); // Import the node into the right document

Element readyToUseElement = (Element)thisDoc.importNode(otherDocElement); // The node never gets appended!!

In this case, you have an element that belongs to the target document, but that never gets appended, or prepended, to anything within the document. The result is another tough-to- find bug, in that the document owns the element but the element is not in the actual DOM tree. Output ends up being completely devoid of the imported node, which can be quite frustrating. Watch out!

6.6 What's Next?

Well, you should be starting to feel like you're getting the hang of this XML thing. In the next chapter, I'll continue on the API trail by introducing you to JDOM, another API for accessing XML from Java. JDOM is similar to DOM (but is not DOM) in that it provides you a tree model of XML. I'll show you how it works, highlight when to use it, and cover the differences between the various XML APIs we've looked at so far. Don't get cocky yet; there's plenty more to learn!

Chapter 7. JDOM

JDOM provides a means of accessing an XML document within Java through a tree structure, and in that respect is somewhat similar to the DOM. However, it was built

specifically for Java (remember the discussion on language bindings for the DOM?), so is in many ways more intuitive to a Java developer than DOM. I'll describe these aspects of JDOM throughout the chapter, as well as talk about specific cases to use SAX, DOM, or JDOM. And for the complete set of details on JDOM, you should check out the web site at http://www.jdom.org.

Additionally, and importantly, JDOM is an open source API. And because the API is still finalizing on a 1.0 version, it also remains flexible.[1] _{You have the ability to suggest and} implement changes yourself. If you find that you like JDOM, except for one little annoying thing, you can help us investigate solutions to your problem. In this chapter, I'll cover JDOM's current status, particularly with regard to standardization, and the basics on using the API, and I'll give you some working examples.

[1] _{Because JDOM 1.0 is not final, some things may change between the publication of this book and}

your download. I'll try and keep a running list of changes on the JDOM web site

(http://www.jdom.org) and work with O'Reilly to get these changes and updates available as quickly as possible.

Full Disclosure

In the interests of full disclosure, I should say that I am one of the co-creators of JDOM; my partner in crime on this particular endeavor is Jason Hunter, the noted author of Java Servlet Programming (O'Reilly). Jason and I had some issues with

DOM, and during a long discussion at the 2000 O'Reilly Enterprise Java Conference, came up with JDOM. I also owe a great deal of credit to James Davidson (Sun Microsystems, servlet 2.2 specification lead, Ant author, etc.) and

Pier Fumagalli (Apache/Jakarta/Cocoon superhero). Plus, the hundreds of good friends on the JDOM mailing lists.

All that to say that I'm partial to JDOM. So, if you sense some favoritism creeping through this chapter, I apologize; I use SAX, DOM, and JDOM often, but I happen

to like one more than the others, because in my personal development, it has helped me out. Anyway, consider yourself forewarned!

7.1 The Basics

Chapter 5 and Chapter 6 should have given you a pretty good understanding of dealing with XML tree representations. So when I say that JDOM also provides a tree-based representation of an XML document, that gives you a starting point for understanding how JDOM behaves. To help you see how the classes in JDOM match up to XML structures, take a look at Figure 7-1, which shows a UML model of JDOM's core classes.

As you can see, the names of the classes tell the story. At the core of the JDOM structure is the Document object; it is both the representation of an XML document, and a container for all the other JDOM structures. Element represents an XML element, Attribute an attribute, and so on down the line. If you've immersed yourself in DOM, though, you might think there are some things missing from JDOM. For example, where's the Text class? As you recall, DOM follows a very strict tree model, and element content is actually considered a child node (or nodes) of an element node itself. In JDOM, this was seen as inconvenient in many cases, and the API provides getText( ) methods on the Element class. This allows the content of an element to be obtained from the element itself, and therefore there is no Text class. This was felt to provide a more intuitive approach for Java developers unfamiliar with XML, DOM, or some of the vagaries of trees.