XOM API for Processing XML with Java

[Elliotte Rusty Harold <elharo AT metalab.unc.edu>]

I'm pleased to announce that XOM 1.0d18, SAX Killer, is now
available from the usual location:

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

1.0d18 adds one minor new feature and one major new feature. The
minor feature is that nu.xom.tests.XOMTestCase  is now public.
This class is very useful for comparing two documents or pieces
thereof for deep equality. For example, I use it to compare the
actual output of the XInclude test cases to the expected outputs.
I'm still working on the API and detailed behavior, but I think
it's solid enough to be useful for other people's unit testing.

Now the major feature, and this one's way cool: It is now
possible to subclass NodeFactory in order to filter and/or stream
your processing. XOM can now handle documents of effectively
arbitrary size with only slightly more memory use than the
underlying SAX parser! I really need to write an article about
this style of mixed tree/stream processing, but in the meantime
here are the key things you need to know:

   1. To enable filtering or streaming, install your own
   NodeFactory subclass with the Builder. I've added a couple of
   constructors to Builder to make this easier.

   2. NodeFactory has one makeNode method for each of XOM's node
   types. You must return a node of the requested type, but you
   can change its name, namespace, value, or other
   characteristics before doing so.

   3. You can eliminate a node from the document simply by
   returning null from the makeNode method. This saves both the
   memory needed to store the node and the time required to build
   it.

   4. To process one element at a time, override endElement() in
   NodeFactory. This supports streaming. Before the builder calls
   this method, it has completely built the element with all its
   content. The usual XOM methods all work on it. You do not have
   process every element in order to process some. You can do a
   quick check on the name and namespace of the element (or other
   characteristics) to figure out what you want to do with it. If
   you don't want to process the element, just return. For example
   an XHTML spider could easily look at each a element and ignore
   all the other elements in the document. Indeed it wouldn't
   even have had to build them or any of their content in the
   first place.

   5. If you only need to process an element once, put your
   processing in the endElement() method and detach() it when
   you're done. As long as you haven't stored a reference to it
   somewhere, the element can then be garbage collected as
   needed. This is how XOM processes documents larger than
   available memory. This is sort of like SAX callbacks, except
   it's much more convenient because you have the entire element
   to work with. You do not need to build a custom data structure
   to hold onto the content until you're ready to work with it.
   The element is its own data structure.

   6. Most importantly, if you don't care about all this, you can
   ignore it. It has no impact on the rest of the API. Adding
   this functionality just required two new protected methods in
   NodeFactory and two new constructors in Builder. The rest of
   the API is unchanged. You can forget about it until you need
   it.

More details are in the JavaDoc for NodeFactory, and I've written
lots of new sample programs that you'll find in the
nu.xom.samples package. Many of them are streaming versions of
earlier, less memory efficient samples.

This developed from an idea proposed by John Cowan, based on
Simon St. Laurent's work with MOE. There have been things like
this before, (DOMBuilderFilter in DOM3, MOE, ElementScanner in
JDOM, and of course SAX filters) but I don't think any API has
done quite as neat a job as XOM now does. This is really powerful
stuff. Not only does it make programs faster and much, much
smaller. It makes them much easier to write. For instance, you
can easily throw away all white space only nodes on build so
you're left with only the real content of the document, no more
white space nodes getting in the way of your navigation. I urge
you to check this out. It will radically change how you think
about processing XML.

This release is API compatible with 1.0d17. All programs that
compiled in 1.0d17 should still compile in 1.0d18 without any
edits.
--

  Elliotte Rusty Harold
  elharo AT metalab.unc.edu
  Processing XML with Java (Addison-Wesley, 2002)
  http://www.cafeconleche.org/books/xmljava
  http://www.amazon.com/exec/obidos/ISBN%3D0201771861/cafeaulaitA