XOM API for Processing XML with Java

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

At 4:30 PM -0500 3/11/04, jcowan AT reutershealth.com wrote:

> A general doco comment:  protected methods should explain whether the
> subclass must, should, or may call the superclass method, and what it does.
> I infer that the provided check* methods do nothing and (so) need not be
> called, but it would be nice to actually know that.

Sometimes a question makes you rethink everything you've done, and 
this may be one of those. Fortunately you asked it before I declared 
API freeze.

I'm pretty sure all the protected methods assume that the subclass 
will override them completely and not call the superclass method. 
There are cases where that doesn't need to be so, but that's been my 
assumption all along. Now suddenly it occurs to me it doesn't have to 
be that way.

Because I was assuming a complete override, I had to make the setter 
and mutator methods (setLocalName, insertChild, etc.) final. To allow 
them to be overridden, I had to make the various fields protected. 
Otherwise they couldn't be changed. And once I made them protected, I 
could no longer enforce well-formedness rules. At least that's what I 
thought, and I'm now realizing I was wrong. I suspect I was too much 
influenced by JDOM which makes its fields protected; but I don't 
really have to do it that way, do I?

The fields can still be private. However the accessor/mutator methods 
don't have to be final. They can call the superclass methods to make 
their changes. As long as the fields remain private and the accessor 
methods are final, this would not enable anyone to violate the 
fundamental class invariant of well-formedness. Subclasses could 
override insertChild, setLocalName, etc. without being able to bypass 
the well-formedness checks.

Advantages:

1. Eliminates a couple of dozen checkFoo() methods. They're no longer 
necessary, and how to subclass XOM classes is a lot more obvious.

2. By overriding insertChild and similar methods a lot more 
possibilities open up. For instance, you'd be able to have the 
equivalent of checkDetach/checkAttach you were asking for yesterday 
with no increase in API complexity. In fact, at a substantial 
decrease. Furthermore, what was ugly to impossible yesterday (e.g. 
automatically inserting a missing BodyElement when someone tries to 
add a PElement to an HTMLElement) becomes possible, and not 
particularly hard or ugly.

Disadvantages:

I can't think of any. It is a significant shift in the API, but it's 
early and this would only affect the protected API. The public API 
would be unchanged.

Am I missing something here? Is there a flaw in this plan that would 
allow subclasses to violate well-formedness? Or is this as big an 
improvement as it appears to me right now?
--

  Elliotte Rusty Harold
  elharo AT metalab.unc.edu
  Effective XML (Addison-Wesley, 2003)
  http://www.cafeconleche.org/books/effectivexml
  http://www.amazon.com/exec/obidos/ISBN%3D0321150406/ref%3Dnosim/cafeaulaitA