[jdom-interest] getChildren() vs getElements()

[Peter V. Gadjokov]

> Wait a second.  The +1s are coming fast and furious but...

You're right, I take mine back, this is more convoluted than I thought,
sorry for jumping the gun (I hadn't considered Jason's issue with the
convenience method and the points you raise below). 

> I think getChildElements() is too verbose and also redundant.  Of
> course it's a child element; what other kind of element would it
> return?  A parent element?  A cousin? :-)

Well, the parent is a possibility but then again, the parent can't be
anything but an element so getParent works fine there. I don't think
getChildElements is so long as to be 'too verbose', you are getting children
and they are elements. 
 
> getElements() is not ambiguous.  It doesn't imply that it recurses any
> more than getChildren() implies that it recurses.  Once you accept
> that an element can contain elements, it is not confusing (it only
> sounds self-referential, but it's not).

The recursion implication is not necessarily that clear - child for
'immediate descendant' and 'descendant' for everything else is pretty common
terminology. getChildElements is a decent hint there is no deep traversal. 
 
> The issue is terminological: there are many "children" of an element,
> but only some of them are elements.  Thus getElements() should return
> the children that are elements, getAttributes() should return the
> children that are attributes, and so forth.

I like this argument (even though Attributes are by definition leaves and
Elements do not have to be) - the naming is simple and consistent. 

> getChildren() should be renamed getElements() 
> 
> (*not* getChildElements(), unless there's a corresponding change to
> getChildAttributes())

I think I buy that (a tentative +1)

> Likewise, getChild() should be renamed getElement().

Same. 
 
> addChild(...) is already deprecated so it's not a problem, though I
> actually believe addChild() is better than addContent() ("content"
> implies "text content of this node" not "some sort of child of this
> node")

This sounds good too but I missed the discussions on that decision so it's
probably another discussion altogether. 
 
> getChildText(String name) is a convenience method anyway, but what
> would be the problem with renaming it getText(String name) ?  The
> presence of the parameter should clear up any ambiguity.

Hmm, this sounds a little iffier to me, name-overloading has its use but the
method name is already fairly terse and just adding a parameter doesn't
really make it that much clearer. But given the new shorter method names, is
the convenience method really needed? element.getElement("foo").getText();
doesn't seem so bad. Neither does something like ElemUtils.getText(Element
elem, String childName) - one can write oneself a personal class like that
if it never showed up in JDOM itself.  Jason, I imagine, would have a
stronger opinion on this. 

> Then removeChild() / removeChildren() / setChildren() should be
> removeElement() / removeElements() / setElements()

Another +1. 

> Following this logic, "getMixedContent()" should be renamed
> "getChildren()" but that would be very confusing at this stage.  I'd
> still vote +1 for it but it would cause a deluge of misguided bug
> reports.

So would I. And yes, it would create some extra noise on the list but
imagine having this debate again after a 1.0 release with a much larger
user-base. Picking a set of names that are clearly and defensibly consistent
is useful and most likely easier to achieve now than later. 
 
> *That's* the proposal.  Not piecemeal, changing one name a dozen
> times.  The whole kit and kaboodle.  We accept, once and for all, that
> a child is not the same as an element.

I'd be happy with all of the above - or any other proposal that is complete
and consistent. I think it would help the discussion if all proposals were
in the same vein - covering all the relevant methods and justifying the
choices. 

-pvg