JDOM Makes XML Easy

Jason Hunter
Co-Creator
JDOM Project

Session #2105
 JDOM Makes XML Easy

"I think JDOM breaks down a lot of

the barriers between Java and XML
and makes it a more natural fit."

-- Simon St. Laurent,

Author XML Elements of Style

Beginning 2 Session #2105

 What is JDOM?

JDOM is an open source library

for Java-optimized XML data
manipulations
This session provides a technical
introduction to JDOM

Beginning 3 Session #2105

 Learning Objectives

• This presentation will teach you...

– Why (and how) we created JDOM
– Where JDOM is most useful
– How to program with JDOM
– How JDOM compares to other technologies
– What's new with Beta 8
– What life is like as an open source JSR

4 Session #2105
 Introductions

• Jason Hunter created JDOM (along with Brett

McLaughlin)
– Jason works as an independent consultant
– Lead author of Java
Servlet Programming,
2nd Edition (O'Reilly,
http://www.servlets.com)

Beginning 5 Session #2105

 Agenda

• The JDOM Philosophy

• The JDOM Classes
• Current Code Status
• JDOM as a JSR

6 Session #2105
 The JDOM Project

• JDOM is...
– A programming model to represent XML data
– Similar to the DOM but not built on DOM or
modeled after DOM
– An open source project with an Apache
license and 2000+ list subscribers
– A Java Specification Request (JSR-102)

7 Session #2105
 The JDOM Philosophy

• JDOM was created to...

– Be straightforward for Java programmers
– Use the power of the Java language (method
overloading, collections, reflection)
– Hide the complexities of XML wherever
possible
– Integrate well with SAX and DOM

Beginning 8 Session #2105

 Scratching an Itch

• JDOM was born in the spring of 2000

– Because DOM and SAX weren't sufficient
– SAX has no document modification, random
access, or output abilities
– SAX often requires building a state machine
– DOM feels foreign to the Java programmer
– DOM is defined in IDL, a lowest common
denominator across languages

Middle 9 Session #2105

 Package Structure

org.jdom

org.jdom.input

org.jdom.output

org.jdom.adapters

org.jdom.transform

10 Session #2105
 The JDOM Classes

• The org.jdom Package

– Attribute – Element
– CDATA – EntityRef
– Comment – Namespace
– DocType – ProcessingInstruction
– Document – Text

• The org.jdom.transform Package

– JDOMSource
– JDOMResult

11 Session #2105
 The JDOM Classes

• The org.jdom.input Package

– SAXBuilder
– DOMBuilder
– ResultSetBuilder
• The org.jdom.output Package
– XMLOutputter
– SAXOutputter
– DOMOutputter
– JTreeOutputter

12 Session #2105
 General Program Flow

XML File XML File

Database Graphics
JDOM
Document
DOM Nodes DOM Nodes

In Memory SAX Events

13 Session #2105
 JAXP and TRaX

• JDOM supports JAXP TM 1.1

– Builders can use any parser, but JAXP
parsers are the default
– JAXP.next may support JDOM directly

• TRaX/XSLT transformations in JAXP

– With JDOMSource and JDOMResult
classes

14 Session #2105
 The Document Class

• Documents are represented by

org.jdom.Document
• They may be constructed from scratch:
Document doc =
new Document(new Element("root"));

• Or built from a file, stream, system ID, URL:

SAXBuilder builder = new SAXBuilder();
Document doc = builder.build(url);

15 Session #2105
 JDOM vs DOM

• To create a simple document in JDOM:

Document doc = new Document();
Element e = new Element("root");
e.setText("This is the root");
doc.addContent(e);

• Or for power users:

Document doc = new Document(
new Element("root").setText(
"This is the root"));

16 Session #2105
 JDOM vs DOM

• The same task in JAXP/DOM requires more

complex code:
DocumentBuilderFactory factory =
DocumentBuilderFactory.newInstance();
DocumentBuilder builder =
factory.newDocumentBuilder();
Document doc = builder.newDocument();
Element root =
doc.createElement("root");
Text text = doc.createText(
"This is the root");
root.appendChild(text);
doc.appendChild(root);
17 Session #2105
 The XMLOutputter Class

• Output is very flexible

Document doc = new Document(...);
XMLOutputter outp = new XMLOutputter();

// Raw output
outp.output(doc, fileOutputStream);

// Compressed output
outp.setTextTrim(true);
outp.output(doc, socket.getOutputStream());

// Pretty output
outp.setIndent(" ");
outp.setNewlines(true);
outp.output(doc, System.out);

18 Session #2105
 The Element Class

• Here's how to navigate the Element tree

// Get the root element
Element root = doc.getRootElement();

// Get a list of all child elements

List allChildren = root.getChildren();

// Get only elements with a given name

List namedChildren = root.getChildren("name");

// Get the first element with a given name

Element child = root.getChild("name");

• That List is a java.util.List!

19 Session #2105
 Managing Kids

• The List is live!

List allChildren = root.getChildren();

// Remove the fourth child

allChildren.remove(3);

// Remove children named "jack"

allChildren.removeAll(root.getChildren("jack"));
root.removeChildren("jack"); // convenience

// Add a new child

allChildren.add(new Element("jane"));
root.addContent(new Element("jane")); // conv.
allChildren.add(0, new Element("first"));

20 Session #2105
 Moving Elements

• Moving elements is easy in JDOM

Element movable = new Element("movable");
parent1.addContent(movable); // place
parent1.removeContent(movable); // remove
parent2.addContent(movable); // add

• It's not so easy in DOM

Element movable = doc1.createElement("movable");
parent1.appendChild(movable); // place
parent1.removeChild(movable); // remove
parent2.appendChild(movable); // error!
• JDOM elements aren't tied to their
Document or build tool!

21 Session #2105
 Well-Formedness

• The Element constructor (and others) check

the element is legal
– No inappropriate characters, etc

LegalRoot

LegalChild A Space Is Illegal

22 Session #2105
 Well-Formedness

• The add/remove method also check

structure
– No loops in any tree
– One and only one root element
– Consistent namespaces
Root1 Root2

Child1 Child2

23 Session #2105
 The Attribute Class

• Elements may have attributes

<table width="100%" border="0"> </table>

// Get an attribute
String width = table.getAttributeValue("width");
int border = table.getAttribute("width")
.getIntValue();

// Set an attribute
table.setAttribute("vspace", "0");

// Remove an attribute or all attributes

table.removeAttribute("vspace");
table.getAttributes().clear();

24 Session #2105
 Element Content

• An Element may have text content

<description>
A cool demo
</description>

// The text is directly available

// Returns "\n A cool demo\n"
String desc = element.getText();

// There's a convenient shortcut

// Returns "A cool demo"
String desc = element.getTextTrim();

25 Session #2105
 Element Content

• Text content can be changed directly

element.setText("A new description");

• Special chars are interpreted correctly

element.setText("<xml> content");

• You can also create CDATA, but it can be

retrieved the standard way
element.addContent(new CDATA("<xml> content"));
String noDifference = element.getText();

26 Session #2105
 Mixed Content

• Elements may contain many things

<table>
<!-- Some comment -->
Some text
<tr>Some child element</tr>
</table>

• Standard uses are kept simple!

String text = table.getTextTrim();
Element tr = table.getChild("tr");

27 Session #2105
 More Mixed Content

• The raw mixed content is also available

List mixedCo = table.getContent();
Iterator itr = mixedCo.iterator();
while (itr.hasNext()) {
Object o = i.next();
if (o instanceof Comment) {
...
}
// Also Comment, Element, Text, CDATA,
// ProcessingInstruction, and EntityRef
}

// Now remove the Comment. Why is it "1"?

mixedCo.remove(1);

28 Session #2105
 Processing Instructions

• PIs look like this

<?br?>
<?cocoon-process type="xslt"?>
Target Data

• They are easy to work with

// Get "target", such as cocoon-process
String target = pi.getTarget();

// Get "data", such as ' type="xslt"'

String data = pi.getData();

// The data is available as attributes!

String type = pi.getValue("type");

29 Session #2105
 Namespaces

• JDOM supports namespaces natively

<xhtml:html
xmlns:xhtml="http://www.w3.org/1999/xhtml">
<xhtml:title>Home Page</xhtml:title>
</xhtml:html>

Namespace xhtml = Namespace.getNamespace(

"xhtml", "http://www.w3.org/1999/xhtml");

List kids = html.getChildren("title", xhtml);

Element kid = html.getChild("title", xhtml);

kid.addContent(new Element("table", xhtml));

30 Session #2105
 Current Status

• Currently JDOM is in Beta 8

• XPath on top of JDOM is quite far along and
usable
– http://www.jaxen.org
• XSLT support is provided via TRaX
– And incorporated in org.jdom.transform
• In-memory validation may squeeze into 1.0

31 Session #2105
 Changes in Beta 8

• Most significant improvements in Beta 8

– Complete rewrite of the List implementation
– Added a Text class to help XPath
– Made I/O classes more featureful
– Added support for internal DTD subsets
– Finalized the EntityRef implementation
– Added Attribute Typing
– Fleshed out well-formedness checking
– Fixed bugs, improved performance

32 Session #2105
 Success Story

• Orange (UK Telecom) uses JDOM to

support their B2B system "Orange API"
– A "Where is my nearest" WAP service
handles 1,000 requests per minute
– That's just 1 of 40 services built on XML
– All their XML processing uses JDOM
– JDOM supports an XML-RPC / SOAP
framework now deployed globally
– Source: Jools Enticknap, Orange

33 Session #2105
 JDOM as a JSR

• JDOM has been accepted as a Java

Specification Request (JSR-102)

• Sun's comment with their YES vote:

• "In general we tend to prefer to avoid adding new
APIs to the Java platform which replicate the
functionality of existing APIs. However, JDOM
does appear to be significantly easier to use than
the earlier APIs, so we believe it will be a useful
addition to the platform"

34 Session #2105
 What It Means

• What exactly does being a JSR mean?

– Facilitates JDOM's corporate adoption
– Opens the door for JDOM to be incorporated
into the Java Platform
– JDOM will still be released as open source
– Technical discussion will continue to take
place on public mailing lists

• http://java.sun.com/aboutJava/communityprocess
/jsr/jsr_102_jdom.html

35 Session #2105
 The People

• Jason Hunter is the "Specification Lead"

• The initial "Expert Group" in order of
acceptance:
– Brett McLaughlin, Jools Enticknap, James
Davidson, Jow Bowbeer, Philip Nelson, Sun
Microsystems (Rajiv Mordani)
– Others are in the process of being added
– All can contribute to technical discussions

36 Session #2105
 Get Involved!

• You too can get involved

– http://jdom.org
– Download the software
– Read the docs
– Read the FAQ
– Sign up for the mailing lists
– Join the discussion

37 Session #2105
 Summary

• JDOM is an open source library for Java-

optimized XML data manipulation
• It was created to be easy to learn, powerful,
and natural for Java programmers
• It uses JAXP and can integrate with DOM
and SAX
• It's an official JSR with a new Beta 8 release
• It makes XML fun!

38 Session #2105
Session #2105
Session #2105