Advertisement

Summary
Elliotte Rusty Harold talks with Bill Venners about the API design principles that guided the design of the XOM (XML Object Model) API, including enforcement of invariants, information hiding for simplicity, and not using assertions for air bags.

Elliotte Rusty Harold is a prolific author of numerous books about Java and XML, and creator of the popular Java website Cafe au Lait and XML website Cafe con Leche. He contributed to the development of JDOM, a popular XML processing API for Java. His most recent book, Processing XML with Java, shows how to parse, manipulate, and generate XML from Java applications using several XML APIs, including SAX, DOM, and JDOM.

At a meeting of the New York XML SIG in September, 2002, Harold unveiled an XML processing API of his own design: the XOM (XML Object Model) API. On Cafe au Lait and Cafe con Leche, Harold described XOM like this:

Like DOM, JDOM, dom4j, and ElectricXML, XOM is a read/write API that represents XML documents as trees of nodes. Where XOM diverges from these models is that it strives for absolute correctness and maximum simplicity. XOM is based on more than two years' experience with JDOM development, as well as the last year's effort writing Processing XML with Java. While documenting the various APIs I found lots of things to like and not like about all the APIs, and XOM is my effort to synthesize the best features of the existing APIs while eliminating the worst.

In this interview, which is being published in multiple installments, Elliotte Rusty Harold discusses the strengths and weaknesses of the various XML processing APIs for Java, the design problems with existing APIs, and the design philosophy behind XOM.

• In Part I: What's Wrong with XML APIs, Harold discusses the five styles of XML APIs and the problems with data-binding XML APIs.
• In Part II. The Good, the Bad, and the DOM, Harold discusses the problems with the DOM API, and the design lessons he learned from DOM.
• In Part III. A Design Review of JDOM, Harold discusses the problems with the JDOM API.
• In Part IV. Lessons Learned from JDOM, Harold discusses the design lessons he learned from the JDOM API.
• In Part V. Design Principles and XOM, Harold discusses the API design principles that guided the design of XOM.
• In this sixth installment, Harold discusses API design principles that guided the design of the XOM (XML Object Model) API, including enforcement of invariants, information hiding for simplicity, and not using assertions for air bags.

Enforcing Class Invariants

Bill Venners: You listed several API design principles in your talk at the New York XML SIG. I'd like to walk through them and get your comments. You said, "It's the class's responsibility to enforce its class invariants."

Elliotte Rusty Harold: XML has rules about names, about where certain things can appear, about how constructs are structured. In an XML API, classes should make sure that XML's rules cannot be violated. If an Element class, for example, has a requirement that the element's name not contain the asterisk character, the class should not rely on the client programmer to feed in only names without asterisks. If the class sees the client programmer trying to do that, the class should throw an exception. I think that is a general design principle, but it is one that is not enforced in a lot of XML APIs. They rely on the client programmer knowing what is and is not legal XML, and only giving their classes legal XML.

Bill Venners: Another design principle you listed in your talks was, "Verify pre-conditions."

Elliotte Rusty Harold: Suppose that a String passed to a method you are writing must not be null, that the method fails if it is null. You should check to see if that String is null. If turns out to be null, even though it was required to be non-null, you should immediately throw an exception before doing anything else, before potentially corrupting the object.

Bill Venners: Bad data shouldn't make an object unusable.

Elliotte Rusty Harold: Any data that is so bad as to make an object unusable when passed to a method should not be accepted by that method.

Bill Venners: And after the exception is thrown, the object should be in the same state as it was before?

Elliotte Rusty Harold: Right. The object should not have changed. The badness of the passed-in data should be detected at the first opportunity.