XOM Design Principles

XOM Design Principles

Elliotte Rusty Harold

Extreme Markup Languages 2004

Wednesday, August 4, 2004

elharo@metalab.unc.edu

http://www.cafeconleche.org/

A few opinions

XML was, as has been fretted over before, ugly, hard, and boring to code with. Not any more :). XOM rocks! I'm using it in all my projects now.

Keep it up!

--Patrick Collison

I did some XML Programming during the last month with Java's DOM. this was not funny !! I also played with Ruby's powerful REXML. this is a great API becaue it uses the power of Ruby and it was designed for Ruby and is not a generic interface like DOM. this is way REXML is so popular in the Ruby world.

and this is why I like XOM. for me it fits much better to Java than DOM. I hope that XOM will become for Java what REXML is for Ruby now.

--Markus Jais

Overall, I found XOM to be an amazingly well-organized, intuitive API that's easy to learn and to use. I like how it reinforces good practices and provides insight about XML -- such as the lack of whitespace when XML is produced without a serializer and the identical treatment of text whether it consists of character entities, CDATA sections, or regular characters.

I can't compare it to JDOM, but it's appreciably more pleasant to work with than the Simple API for XML Processing.

--Rogers Cadenhead

i spent yesterday writing the code to render my application config as xml. using xom was like falling off a log. no muss, no fuss, the methods did what i expected, and any confusion was quickly ironed out by a visit to the (copious) examples, or the javadocs. i did run into what might be a bug, but it only showed up because i made a dumb cut-n-paste error (see my other email).

after i get the output tidied up, i'll move on to reading it back in. i'm confident that that will be almost as easy...

--Dirk Bergstrom

Why Me?

Four Styles of XML API

• Event Based Push: SAX, XNI

• Event Based Pull: XMLPULL, CyberNeko, StAX

• Tree: DOM, JDOM, dom4j, Sparta, etc.

• Data Binding: Castor, Zeus, JAXB, JaxMe, etc.

DOM

• Uses factories and interfaces, and yet not interoperable

• Fails to enforce all XML constraints; allows creation of malformed documents

• Namespaces properties and attributes

• Just plain ugly; does not adhere to Java conventions

DOM Ugliness

• No method overloading

• Short type constants for node types

• Methods in the Node superinterface that only work for one or two subinterfaces

• Incomplete: no standard loading or serialization

• A single exception class with short type codes

• Does not guarantee Java features like equals(), hashCode(), and toString()

What I learned from DOM

• A node supertype is very useful

• Interfaces are a bad idea

• Successful APIs must be simple

JDOM

• Simplest of the existing APIs (but it could be simpler)

• There's more than one way to do it:

  • 3+ ways to read an attribute value

  • 5+ ways to read a child element

• Not always well-formed:

  • Processing instruction data

  • Text content

  • Internal DTD subset

• Setter methods don't return void

Is JDOM too Java-centric?

• Too weakly typed: Everything is an Object

• Too strongly typed: nothing is a Node

• Cloneable

• Serializable

• Many checked exceptions

What I learned from JDOM

• Classes and constructors are good

• Thread safety is not necessary

• Keep everything in one package

• Don't release too early

• Don't optimize until the API is right

• You don't need to build your own parser, transformer, or query engine

• You can fight the W3C

dom4j

• Forked from JDOM in the wrong direction

• More complex

• Uses interfaces instead of classes

Conclusion: We can do better

nu.xom: A New XML Object Model

• A complete streaming tree model for XML 1.0 instance documents

• Free as in speech (LGPL)

• Pure Java

• Java 1.2 and later (internal dependence on Collections API)

Design Goals

• Absolutely correct

• Easy to use

• Easy to learn

• Fast enough

• Small enough

• No gotchas

XML Principles

• All objects can be written as namespace well-formed, round-trippable XML text

• Impossible to create malformed documents

• Validity can be enforced by subclasses

• Syntax sugar is not represented:

  • CDATA sections

  • Character and entity references

  • Attribute order

  • Defaulted vs. specified attributes

Design Principles

• Principle of Least Surprise

• As simple as it can be and no simpler!

• Use Java idioms where they fit (and only where they fit)

• There's exactly one way to do it

• Start small and grow as necessary:

  • It's easier to put something in than take something out.

    if I may make one point that highly influenced the end-game when we were finishing up XML 1.0 in 1998: if you leave something out, you can always put it in later. The reverse is not true.

    --Tim Bray on the public-qt-comments mailing list

  • During the design I added methods that were necessary to produce certain sample programs.

Principles of API Design

• APIs are written by experts for non-experts

• It is the class's responsibility to enforce its class invariants

• Verify preconditions

• Do not allow clients to do bad things.

• Hide as much of the implementation as possible.

• Design for subclassing or prohibit it

• Prefer classes to interfaces

• APIs are by their nature paternalistic

Java Design Principles

• Not thread safe

• Classes do not implement Serializable; use XML.

• Classes do not implement Cloneable; use copy constructors.

• Lack of generics really hurts in the Collections API. Hence, don't use it.

• Problems detectable in testing throw runtime exceptions

• Assertions that can be turned off are pointless

Development Style

• This is a cathedral, not a bazaar

• Unit testing

• Static testing

• Massive samples

Performance

• "Premature optimization is the root of all evil" -- Donald Knuth, 1974

• Pretty damn good

• Fast enough

• Certainly one of the most memory efficient, tree-based APIs; possibly the most memory efficient

How does XOM differ from JDOM?

• Absolutely correct; no malformedness

• Fewer "convenience" methods and classes

• toXML()

• JDOM Elements contain a list; a XOM Element is a list; thus

• Typed navigation via loops instead of the Java Collections API, Lists, and Iterators

• No support for skipped entities

• XOM classes do not implement Serializable or Cloneable

In JDOM's Favor

• XPath Support

In XOM's Favor

• Streaming

• Canonical XML Support

• XInclude Support

XOM is simpler!

^* Content

^** SAXBuilder

Current version

• 1.0a5: alpha, API freeze

• 1.0 beta 1: all known bugs fixed

• 1.0: Documentation complete

Props

• Joshua Bloch for Effective Java

• Ken Arnold for Perfection and Simplicity

• Bruce Eckel for Does Java need Checked Exceptions?

• Bertrand Meyer for Object Oriented Software Construction

• Jason Hunter and Brett McLaughlin for JDOM

• Kent Beck and Erich Gamma for JUnit

• The members of the xom-interest mailing list for numerous helpful suggestions and critiques

To Learn More

• XOM Site: http://www.cafeconleche.org/XOM/

• XOM-interest mailing list: http://lists.ibiblio.org/mailman/listinfo/xom-interest

• Getting Started with XOM by Michael Fitzgerald, http://www.xml.com/pub/a/2002/11/27/xom.html

• XML Made Simpler by Rogers Cadenhead, Linux Magazine, March 2003, http://www.linux-mag.com/2003-03/java_xom_01.html

• nu.xom.samples package has simple example of many XOM features.

• This presentation: http://cafeconleche.org/slides/extreme/xom/