A Conversation with Elliotte Rusty Harold, Part VIII

---

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 Part VI. Air Bags and Other Design Principles, 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.
• In Part VII. Design by Dictatorship, Examples, and Tests, Harold discusses the benefits of a having single decision maker for an API design and insights gained through writing examples that use the API.
• In this eighth installment, Harold discusses the readability of XML documents and the code that processes them.

Parsing XML into XOM Subclasses

Bill Venners: I would like to ask you about readability of XML and code that processes XML. I have used both JDOM and JAXB to process XML in Java. One aspect of JAXB that I really liked was that it allowed me to represent my parsed documents in classes that map to the concepts of my document's schema. With JDOM, as with XOM, the classes map to the general concepts of XML documents, not to specific concepts of the particular schema. In your talk to the New York XML SIG you said something that I believe may concern parsing XML documents into classes that more closely model schemas. You said, "Factories can be used to build subclasses during parsing." What did you mean by that?

Elliotte Rusty Harold: Allowing subclasses to be built during parsing is another trick I learned from JDOM. I did not invent this myself. Even though I didn't copy much code from JDOM, I did copy lots of ideas, and that's one of them.

When XOM's Builder object, the parser in essence, reads an XML document, it does not call the constructors directly for the Element, Attribute, or Text classes. XOM is a class-based, not an interface-based, API, so those classes do have public constructors. But rather than calling those constructors directly, the Builder calls a factory that then calls the constructors.

This approach allows you to substitute a different factory on top of the parser. For example, if you substitute an XHTML factory, it can look at the data and say, "OK. We're being asked to create an element, and the name of the element is table. Therefore, I'm going to return my special TableElement object, rather than a generic XOM Element object."

Bill Venners: And TableElement extends Element.

Elliotte Rusty Harold: Right. It allows you to plug in your own subclass hierarchy.

XML Schema Compilers and Code Readability

Bill Venners: That subclass hierarchy reminds me of JAXB, where classes map to the concepts represented in the data, not just to XML concepts. For example, classes that represent description or link elements in RSS, not just Element and Attribute.

Elliotte Rusty Harold: I'm not up on the latest version of JAXB. I've skimmed through the specification and looked at it a little bit. I think the big difference with JAXB is that when you unmarshal, in their terminology, the XML document into their hierarchy, you really throw away a lot of the XML. You've lost a lot of things. And then that has to be marshaled back out into the XML if that's what you want. XOM would never lose track of the XML.

The other practical difference is that in XOM you would have to write your own class libraries and hierarchies by hand. You would not have it built directly for you by a schema compiler as in JAXB. So you'd have to write a TableElement class, a BodyElement class, a DivElement class, and so forth. So it would be a lot more work. But if you're doing it for something like XHTML, it might be a product that's shared across multiple groups and multiple developers, so the cost might be spread.

Bill Venners: What I was imagining, though, was that something like a schema compiler could generate subclasses of XOM's Element class.

Elliotte Rusty Harold: That's a very interesting idea. I hadn't thought of that.

Bill Venners: I prefer parsing XML documents into objects that conceptually represent a schema's data model, because the code is more explicit. But that approach only makes sense if a schema exists and you can require that all documents strictly adhere to that schema. It isn't appropriate in all situations.

Elliotte Rusty Harold: Right, but if you had a schema, or could write a schema, it might be easier to write the schema than to write the individual classes. Even if it's not a W3C XML schema language schema, even if it is just an XML document that describes the classes you're going to need. Hell you could even write the compiler in XSLT if you wrote the schema in XML. It's a very interesting idea. I hadn't thought of it. It would take some work, but it might save a lot more work on the other end.

Readability of XML Documents

Bill Venners: <?xml version="1.0" standalone="yes"?><deepquestion>To what extent is XML suitable for tasks in which humans, not just software, will be reading the documents?</deepquestion>

Elliotte Rusty Harold: <?xml version="1.0" standalone="yes"?><thoughtfulresponse>I think XML is clearly suitable for both tasks. I wrote an entire book in XML using a text editor. I wrote the next book in OpenOffice Writer, a traditional GUI word processor. I think the first book, written in XML, was much easier to write. <shamelessplug>Processing XML with Java</shamelessplug> was written in DocBook using JEdit, BBEdit, and UltraEdit -- plain vanilla text editors with no understanding of XML whatsoever. And I think that worked well for me. Certainly it works well for a developer, somebody with a developer's mind. Would I necessarily give this to a secretary and ask them to write XML? Maybe not, but I have known secretaries who spent their day typing TeX. And certainly XML is easier to use than TeX.</thoughtfulresponse>

Bill Venners: <?xml version="1.0" standalone="yes"?><sizematters>I have no problem reading the small XML documents that I have for each HTML page on my web site. They are flat XML documents with a dozen or so elements for the title, subtitle, author, and so on. I edit those files by hand with vi mostly, and it works great. On the other hand, I tend to get lost in Ant files. When I look up how to do something with Ant, the syntax often seems hairy and difficult. XML doesn't seem as natural to me as a traditional context free grammar. I think people sometimes use XML in places where a traditional context free grammar would be better.</sizematters>

Elliotte Rusty Harold: <?xml version="1.0" standalone="yes"?><syntaxmatters>You can certainly develop an obfuscated syntax in XML, a syntax that is hard to read -- just as you can in other languages. <obfuscatedsyntax><And>Just</And> <he>putting</he> <slams>something</slams> <the>into</the> <point>XML</point> <home>does</home> <with>not</with> <an>automatically</an> <innovative>make</innovative> <self-referential>it</self-referential> <example>clear</example></obfuscatedsyntax>. But I think in general with sufficient effort and care and thought, you can design XML formats that are plausible to read and plausible to understand.</syntaxmatters>

Next Week

Come back Monday, September 15 for the next installment of a conversation with C# creator Anders Hejlsberg. The final installment of this conversation with Elliotte Rusty Harold will appear September 22. If you'd like to receive a brief weekly email announcing new articles at Artima.com, please subscribe to the Artima Newsletter.

Resources

Elliotte Rusty Harold is author of Processing XML with Java: A Guide to SAX, DOM, JDOM, JAXP, and TrAX, which is available on Amazon.com at:
http://www.amazon.com/exec/obidos/ASIN/020161622X/

XOM, Elliotte Rusty Harold's XML Object Model API:
http://www.cafeconleche.org/XOM/

Cafe au Lait: Elliotte Rusty Harold's site of Java News and Resources:
http://www.cafeaulait.org/

Cafe con Leche: Elliotte Rusty Harold's site of XML News and Resources:
http://www.cafeconleche.org/

JDOM:
http://www.jdom.org/

DOM4J:
http://www.dom4j.org/

SAX, the Simple API for XML Processing:
http://www.saxproject.org/

DOM, the W3C's Document Object Model API:
http://www.w3.org/DOM/

ElectricXML:
http://www.themindelectric.com/exml/

Sparta:
http://sparta-xml.sourceforge.net/

Common API for XML Pull Parsing:
http://www.xmlpull.org/

NekoPull:
http://www.apache.org/~andyc/neko/doc/pull/

Xerces Native Interface (XNI):
http://xml.apache.org/xerces2-j/xni.html

TrAX (Tranformation API for XML):
http://xml.apache.org/xalan-j/trax.html

Jaxen (a Java XPath engine):
http://jaxen.org/

RELAX NG:
http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=relax-ng

Talk back!

Have an opinion? Be the first to post a comment about this article.

About the author

Bill Venners is president of Artima Software, Inc. and editor-in-chief of Artima.com. He is author of the book, Inside the Java Virtual Machine, a programmer-oriented survey of the Java platform's architecture and internals. His popular columns in JavaWorld magazine covered Java internals, object-oriented design, and Jini. Bill has been active in the Jini Community since its inception. He led the Jini Community's ServiceUI project that produced the ServiceUI API. The ServiceUI became the de facto standard way to associate user interfaces to Jini services, and was the first Jini community standard approved via the Jini Decision Process. Bill also serves as an elected member of the Jini Community's initial Technical Oversight Committee (TOC), and in this role helped to define the governance process for the community. He currently devotes most of his energy to building Artima.com into an ever more useful resource for developers.