XOM API for Processing XML with Java

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

One of the tasks in the TODO List has been to consider whether the 
ParsingException class, or perhaps the Builder, should have a means 
of returning  the Document parsed before the first well-formedness 
error. I've been experimenting with that, and I'm now prepared to say 
why I think that's a bad idea (contrary to my initial impressions). 
I'm sending this message mostly to go on the record in the archives 
about this so in a year when somebody else suggests this feature, I 
can remember why I don't like it.

First why it might be a good idea. In a streaming API such as SAX or 
StAX it is common to process the initial parts of a document before 
the rest of the complete document has been seen. For example, if 
you're receiving a large document over the network which contains 
thousands of minute by minute stock prices, you may wish to act on a 
good price before the end-tag is sent at the close of the trading 
day. In such an example, you may have already acted on previous data 
before a well-formedness error is seen.

This is legal according to the XML spec. parsing must stop once a 
well-formedness error is encountered. However, there's no rule that 
says you have to throw away what you've already read. In practice, 
streaming APIs have retained the content and tree-based APIs have 
thrown it away. Indeed, deciding when to throw away already processed 
content and how to rollback is one of the thornier problems for 
streaming API based applications.

My idea was to enable this in XOM by adding a getPartialDocument() 
method to the ParsingException class which would return whatever the 
Document in whatever state the Builder had built it when the 
exception first occurred. You wouldn't have content from after the 
well-formedness error, but you could still use the earlier, 
presumably good parts of the document.  After some experiments and 
some debugging I think I've decided against that, and I wanted to say 
why.

The first and less important reason is that XOM already supports 
streaming through the NodeFactory class. If you need access to 
document fragments before the well-formedness error, you can have 
them. It wasn't clear that putting partial documents in the 
exceptions really let anybody do anything they couldn't do now. It 
was more of a convenience than anything else.

However, the much more important reason was that as I looked at 
different cases I discovered that doing this might actually hide the 
errors. For example, consider this simple malformed document:

<root><child1/><child2>

By the time the well-formedness error is detected, the parser has 
built this document instead:

<root><child1/><child2/></root>

The following case with a issing child1 end-tag is worse:

<root>
  text
  <child1>
  <child2/>
  <child3/>
</root>

The builder adds a lot of content to the child1 element before 
detecting the problem. What I really want as a partial document here 
is

<root>
  text
  <child1>


However what I get is

<root>
  text
  <child1>
    <child2/>
    <child3/>
  </child1>
</root>

The malformedness has significantly changed the shape of the 
document. In the face of a well-formedness error it just isn't 
possible to figure out what the document is really supposed to look 
like. Providing the partial document could be actively misleading.

What's truly damning is that the same structure could be produced by 
several documents with malformedness errors in different places. For 
instance:

<root>
  text
  <child1>
    <child2/>
    <child3/>
<!-- </child1> -->
</root>

and

<root>
  text
  <child1>
    <child2/>
    <child3/>
  </child1>
<!-- </root> -->


And these are simple cases. As documents get longer and more complex 
it becomes harder and harder to tell just where the real problem lies.

So I'm crossing this one off the To-Do list. Anyone who has a 
particular need for processing the initial parts of a malformed 
document can still do so using NodeFactory at their own risk. 
Presumably programmers with more knowledge of what the documents 
should look like can do a better job of figuring out where the first 
error really is; but I don't think XOM should try to do it for them.

--

  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