[jdom-interest] Last call: getChild/getChildren versus getChildElement/getChildElements

[Jason Hunter]

I'm a little worried I'm going to get yelled at when I release beta10 
deprecating getChild() and getChildren().

If you haven't been paying attention to CVS, we added a Parent/Child 
pair of interfaces and as part of that changed getChild(String) to 
getChildElement(String) which we thought was more descriptive and less 
likely to be confusing considering a Child interface applies to types 
Element, Text, EntityRef, Comment, PI, and so on.  Also getChildren() 
and getChildren(String) became getChildElements() and 
getChildElements(String) for the same reason.

Such a late deprecation is likely to peeve some people who wrote a lot 
of JDOM code.  Heck, it peeves me.  I'm thinking now we should just keep 
getChild() and getChildren() and document them for what they are and 
leave it at that.  JDOM's been around for *4 years* now and even though 
we haven't called it 1.0 and have reserved the right to change the API, 
changing a core method at this late date seems wrong.

Might the names be confusing?  Perhaps.  But people are already used to 
getChild/getChildren.

And here's more ammo.  What does $foo/child::* return in XPath/XQuery? 
All the child elements!  So getChildren() makes perfect sense in that 
view.  And $foo/child::bar returns all child elements named "bar" which 
would correspond to getChildren("bar").  It's not 
$foo/child-elements::*.  I think XPath got the "child" idea better than 
DOM did.

I do wonder if we should change the Child interface name to Content. 
getContent() returns content, but everything right now is of type Child. 
   As a bonus, if we changed Child -> Content nothing would break since 
Child is new.  After all, what should getContent(int) return?  Not a 
Child, it should be a Content.

Do we need to change Parent's name then?  I'm thinking not since 
getParent() should return a Parent.  Yes, we'll have a Parent/Content 
pairing which doesn't roll off the tongue, but hey, at least everyone 
won't have to change all their getChild() and getChildren() calls, we'll 
have getContent() return Content, and I won't get yelled at.

So here's my proposal:
* Change Child to Content
* Remove getChildElement and getChildElements
* Undeprecate getChild and getChildren

-jh-