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

[Alex Chaffee]

> getChildElements makes perfect sense, because an Element can easily
> refer to other elements than its own children.

"Easily?"  I think it would be very difficult to interpret
getElements() as returning anything but its own children.

That is, there are a certain number of common-sense first-blush
interpretations about what getElements() would return.  All of these
interpretations would be cleared up with a simple look at the JavaDoc,
but for the sake of those seat-of-the-pants desperadoes who just hack
out code based on "javap org.jdom.Element", then post urgent messages
to jdom-interest after their first compile-time error, we would do
well to examine these interpretations.

Interpretation 1:  getElements() returns the child elements one level deep

This is the correct interpretation and feels natural to anyone who's
used Java collections.

Interpretation 2:  getElements() returns the child elements all levels deep

There is no collection class in java.util, or most anywhere else, that
recurses by default.  In fact, suggestions to add getAllElements() or
equivalent have been dissed by Jason with "just use a recursive
Iterator loop like everyone else" implying that that's The Right Way
to get all elements recursively.  Also, it can be expensive to get all
children, so that's another reason to assume it does not recurse.

Interpretation 3:  getElements() returns the parent element

Yeah, right :-)

Interpretation 4:  getElements() returns all sibling elements

Anyone with a basic concept of tree structure would not expect a child
to refer to its siblings unless through an explicitly-named
getSiblings() or getNextChild() etc.

Are there any other elements that an element could "easily" refer to?

Brett, I hope this helps you work through your phobia of getElements() :-)
I really believe it's not ambiguous, and that its ambiguity is the
only potential problem.

 - A

-- 
Alex Chaffee                       mailto:alex at jguru.com
jGuru - Java News and FAQs         http://www.jguru.com/alex/
Creator of Gamelan                 http://www.gamelan.com/
Founder of Purple Technology       http://www.purpletech.com/
Curator of Stinky Art Collective   http://www.stinky.com/