[jdom-interest] Ideas for API changes

[Tom Bradford]

Jason Hunter wrote:
> > How would it be any more complex than it already is?
> 
> Because then the developer has to learn what these new interfaces do.
> The more classes and interfaces in an API, the more complicated it is to
> learn.

Untrue.  I use Java on a daily basis and I don't need to know which
classes implement Cloneable, Comparable, Serializable.  These are all
marker interfaces that Java does something with outside of the normal
scope of using the implementing classes, and it would be no different
defining a marker interface for contraining tree management, other than
the marker is used as a base-class signature of sorts.

   elem.addContent(new Element("blah"));

   or 

   Element elem = new Element("blah");
   oldElem.addContent(elem);

How is this any different than the way you interact with the library
now?  Most people will tell you that they don't care that a marker class
is being used for the signature, so long as the method call works. 
That's the beauty of OOP.

> > The marker
> > interfaces would never have to be exposed to developers,
> 
> They're there when they read the Javadocs!!  Plus, when a developer
> looks for an addContent(ProcessingInstruction) method they won't find
> it.  They have to know PI is an ElementChild.  They shouldn't have to
> know that or think about that.

We're talking about a sorta-DOM implementation, not rocket science.  Put
to a vote, I doubt many people would care.  Instead of 5 JavaDoc
entries, you have 1, where if someone clicks on the ElementChild link in
the method signature, they'll quickly find out which classes implement
it.  Heck, you could even tell them right in that *1* bit of JavaDoc. 
Then when/if you ever add or remove constraint support, you change a bit
of JavaDoc, and remove an "implements" snippet from a class definition.

Your life is simpler, the code is simpler, you have reusable
functionality, everyone's happy.  Oh, and for a brief second a
developers head will spin trying to figure out what class implements
what.  Small price to pay.  Developers are smart, they'll get it.

-- 
Tom Bradford --- The dbXML Project --- http://www.dbxml.org/
We store your XML data a hell of a lot better than /dev/null