[jdom-interest] API Inertia

[Jason Hunter]

Brett McLaughlin wrote:
> 
> > Iterator itr = doc.getContentIterator();
> > while (itr.hasNext()) {
> >   Object o = itr.next();
> >   // deal with o
> > }
> 
> What if I want to start iteration at an Element? No commonality? So we've
> got to write special-case code for the iterator on Document and Element?

Having it on Document and Element makes sense.  The Document impl would
call the Element impl recursively probably.

> > Having a Node interface doesn't really help here because Iterator
> > returns Object.  Always will.  You could cast to Node but it'd be
> 
> Why? Who says it must? I guess I'm not convinced that assumption is valid.
> And if it's simply because of java.util.Iterator, call it TreeWalker or
> something and make it return type-safe values. 

Let's call it NodeList!

Er, wait a second.  That's DOM!

> > There's some value here.  But XMLOutputter would have to do an
> > instanceof search to determine what type of object it truly was and then
> > use different logic internally depending on the class, because Node
> > wouldn't have any helper methods to handle output.  That means you end
> 
> So? XMLOutputter internals should not affect the determination of the
> usefullness of a method. That is a totally silly argument, IMO ;-) 

Brett, you know me better than to think I make silly arguments.  It's
not that I'm worried about the "XMLOutputter internals".  It's that I'm
worried about exposing a *false* API.  If XMLOutputter has an
output(Node) method and in reality it can't output Amy's funky
Node-implementing classes which she wants to write, then it's *lying*
about what it can output.  An output(Node) method only makes sense if
Node has a way to help the output, as if Node had a getSerializedForm()
method.  But you want to use this to *avoid* getSerializedForm().  So
you're stuck.

In case anyone's not following me, think back to CS 101 where you
learned OOP with the ubiquitous Shape interface.  You had concrete
classes Triangle, Square, etc but each implemented Shape.  Now, Shape
had a paint() method so all shapes could be displayed.  If I created an
Octagon I'd implement paint() and it could be passed to a draw(Shape)
method just fine.  But if Shape had no paint() method, than a
draw(Shape) method couldn't really draw any general shape, only two
particular classes that happened to implement Shape.  Therefore the
draw() method shouldn't advertize it can print a Shape.

> As an API
> user, I couldn't care less how hard the API writer has it; I care about what
> the API does for me.

Me either, see my recent post.  Glad you're in agreement that
complicating the API to make it easier to implement isn't worthwhile. 
:-)

> Not true. It would be able to print every implementing class of Node, which
> isn't a lie at all. Unless you go to the rather ridiculous, Jonathan Swift
> style satire of saying someone defines there own Node implementation that's
> nutty and passes it in. 

But Amy has plans already!  If you open that door, people are going to
implement their own Nodes.

> Simply that I don't want inertia to be a factor, and I feel that it is, to
> some extent. Not to an extreme, but I think there's a "I tried that, and it
> didn't work, and there's no way that any light can be shed on it that I
> didn't already think of." I'm not sure that's the case. 

I haven't seen anything yet (except ElementChild) which I hadn't
investigated already in my own experimentation or which wasn't suggested
by someone on this list last time we hashed this out.  But you'll notice
I haven't just said, "Trust me it won't work".  I've tried to explain
the problems I see with each plan.


But, to be honest, I get a limited amount of time to work on JDOM and
recently it's *all* been debating about these issues.  I want JDOM done
this autumn.  I want that because people need and deserve a 1.0 (it's
been a year since we created JDOM), and because I have only so much
energy and so much time away from other duties I can expend here. 
There's *tons* of work to do before we're at 1.0.  I'm not getting a
whole lot of support on pushing forward (i.e. factory patch review),
just a lot of debate on the direction in which to move.  The ones who
are doing the most now to support JDOM (Phil and Jools) are in agreement
with me on the latest issues, so I'm feeling good about that.  I have to
daily choose between debate and coding progress (and having a life at
night), and the pendulum is swinging toward coding.  Come autumn I want
it to swing to having a life.

-jh-