One of my favorite things about JDOM is that, 90 percent of the time, it works exactly the way I expect it to work. I don't have to look at the documentation because my best guess is almost always right. This is only sometimes true for SAX and almost never true for DOM. For example, suppose you wanted to create the JDOM representation of this element:
The simplest, most obvious solution I can imagine is this:
Element element = new Element("fibonacci");
Guess what? That's exactly how you do create an element in JDOM. Compare that with the DOM approach:
DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance(); DocumentBuilder builder = factory.newDocumentBuilder(); DOMImplementation impl = builder.getDOMImplementation(); Document doc = impl.createDocument( null, "Fibonacci_Numbers", null); Element element = doc.createElement("fibonacci");
I think any sane developer would agree that JDOM is simpler, at least for this initial example.
Now suppose you want to give the element some text content like this:
Here's the first thing that occurs to me:
Element element = new Element("fibonacci"); element.setText("8");
Guess what? That works. It is exactly how JDOM fills an element with text. Unlike DOM, you don't have to create any separate text nodes. JDOM does use a Text class internally, but you don't need to know about that. You can just use strings.
Now suppose you want to add an attribute to the element like this:
The first thing that occurs to me is this:
Element element = new Element("fibonacci"); element.setText("8"); element.setAttribute("index", "6");
Once again, the most obvious solution is the correct solution. This is a running theme in JDOM. Try the simplest thing that could possibly work, and chances are it will work.
On the other hand, there are some limits to simplicity, mostly established by XML. JDOM strives to be as simple as it can be and no simpler. It does not hide the genuinely complex parts of XML. For example, it faithfully reproduces all the complexity of XML namespaces, including the parts that have occasionally been labeled "psychotic." More specifically , it allows the same prefix to map to different URIs in different parts of the document. This compares favorably with some other APIs (I'm thinking of ElectricXML here) that pretend XML is simpler than it really is. In general, if something is complex in JDOM, it's because that same something is equally complex in XML.
Of course many elements contain child elements, comments, processing instructions, and other things besides pure text. In this case, you can attach them by calling the addContent() method. For example, suppose you want to create this element:
<sequence> <number>3</number> <number>5</number> </sequence>
First you need to create three Element objects, two for number elements and one for the sequence element. Then you need to add the number elements to the sequence element in the order you want them to appear. For example:
Element element = new Element("sequence"); Element firstNumber = new Element("number"); Element secondNumber = new Element("number"); firstNumber.setText("3"); secondNumber.setText("5"); element.addContent(firstNumber); element.addContent(secondNumber);
Actually I've cheated a bit here. What this really produces is this element:
White space is significant in XML and thus significant in JDOM. If you want the nicely indented element, you also need to add some strings containing the appropriate white space, as follows :
Element element = new Element("sequence"); Element firstNumber = new Element("number"); Element secondNumber = new Element("number"); firstNumber.setText("3"); secondNumber.setText("5"); element.addContent("\n "); element.addContent(firstNumber); element.addContent("\n "); element.addContent(secondNumber); element.addContent("\n");
If you only care about the extra white space when the document is serialized, you can ask an XMLOutputter to insert it for you. I'll cover this soon.