[jdom-interest] Ideas for API changes

[Trimmer, Todd]

I whole-heartedly agree with Tom Bradford's approach to a bigger
class/hierachy interface (ElementChild, DocumentChild, etc.). This way, the
object hierarchy becomes a better analogue for the problem we are tyring to
solve. The relationships between the various JDOM objects becoming
immediately apparent by examing the hierarchy itself. Heck, if a programmer
came across the API and didn't know anything about XML, he could gleam some
of the rules of XML by studying the hierarchy tree by itself.

	Very few applications will ever cast explicitly to the "lower-level"
interfaces like ElementChild, and then have that reference hang around -- it
will be used almost immediately. Likewise, it's improbable he will create an
external reference to one of these types, unless, once again, it's for
immediate consumption. This is why the developer will spend little time
learning these interfaces. He can quickly see that they exist solely more
more robust compile-time checking and allow methods to cascade down to the
more advanced classes that inherit from it. So all the arguments about
increased complexity are pretty weak. There are plenty of packages in Java
having classes/interfaces that classes/interfaces that do little more than
organize code and structure in a more logical fashion. This is good OO
people! So even if a say a Node interface has nothing more than a
getParent() method, there is still something to be gained (and unlike DOM, I
do not consider a Document to be a node at all. It is a databed for all the
nodes that comprise it. So cries of "But getParent() doesn't make sense with
a Document!" doesn't phase me much -- I wouldn't make Document implement
Node anyway).

	And yes, programmers will still need to downcast from Object when
retrieving Nodes from Collections. However, if I were able to immediately
downcast to Node without even thinking about it, I can get away with some
quick-fire stuff for activities like tree walking.

Now let's pause for a second. More than one person has decreed that tree
traversal is a specific application of JDOM and not in and of JDOM itself,
and therefore JDOM should not have tree traversal API. Who are you kidding?
How can you ignore the fact that XML is based on the classic computer
science structure -- the tree? I daresay an application that doesn't take
XML's hierarchical nature into consideration to be MORE specific than a tree
traversing one!


Let's pause for another second to pick on Jools ;-)
<mayhem:pick-on target="Jools">

"So we have an interface with two methods ? Well that sounds like a complete
waste of time."

	Is java.lang.Runnable a waste of time since it has a single method?
Think quality; not quantity. Again, it's the closer analogue to the problem
we are trying to represent we are striving for.

"Context is everything. It's a Node when it's inside the Tree, but 
what I want is to ask for an Element.

So when I 'get' the Node from the tree, I have an Element. Not a Node."

	The magical word, "context", conjures up XPath support. Plus, you
are not restricted to the immediately descendants of the Element/Document
you're getting from; it's just a starting point.

	If you want to have Element return only the children that are also
Elements, then by all means leave Element::getChild() and
Element::getChildren() alone (backwards compatibility bonus) and have the
Node method be getMixedContent() -- something which Element will have a
headstart on implementing =)

What do we get with this?
1) Zero casting when getting Elements from Elements
2) Robust compile-time type checking and consolidation of addContent methods
3) Quick tree traversal
4) Hierarchy that accurately portrays the relationships between XML's parts.
5) Collections are still as best as collections can possibly be considering
Java has no parameterized types
6) XPath still returns Lists (why do people testify that it returns Object?)
</mayhem:pickOn>


	There was an argument that tree traversing acts upon XML's
structure, and not it's logic; and the JDOM API should act upon logic alone,
with structure functionality being delegated to extensions.

	How can I divorce structure from logic when dealing with XML? It's
not an ADT, where I either manipulate it as a whole or deal with data coming
in and out of it. I can maintain several independent iterators that can
attach to different points, and they can ALL modify the structure. Because
the XML tree is naked to the programmer, structure API should be included.

Todd Trimmer