[jdom-interest] getChild() vs. getChildElements()

[Patrick Dowler]

On Tue, 01 Aug 2000, you wrote:
> At 9:03 PM -0700 7/31/00, Jason Hunter wrote:
> 
> 
> > And since we looked at the
> >Collections APIs for whether to return null or not, let me point out
> >they shortened the "addElement" name down to just "add".  :-)
> >
> 
> However in the Collections API everything in a Vector/List/etc. is an 
> element and element has a very generic meaning. It's not merely one 
> of several different types that may appear in the collection. The 
> analogy doesn't hold. In the context of the Collections API the word 
> "Element" more closely maps to the word "Child" in an XML context.

However (again), in the Collections API, it is add(Object) whie in JDOM you can
only add specific types. That said, I suggested a while back (during the great
change debate) that addXXX could be shortened to just "add" and overloaded to
add the farious types that were allowed. That makes only one "add" method
in the API instead of several. The same can be said for "remove" - overload it
and keep the API small. 

...back to the suubject at hand...

As for the "getChild/getChildren vs getChildElement/getChildElements"
my feelings are:

- getChildElement and getChildElements look really similar when you are
quickly scanning some code for obvious errors or behaviour. In that sense
alone, I prefer the former pair of methods because they look more different
visually.

- a small nit: Are there any other elements to get, aside from child elements? 
Since the answer is "no", why is the word "child" needed at all? No one would
expect to get siblings or grand-children.

Now I get to "however" myself :-)

If we were folllowing the style of the Collections API, these methods would be:

	Element get(String name) { }

	List getAll() { }  // gets all Elements - don't like this one
	List getElements() { }  // gets all Elements - this looks better
 	List getMixedContent() { }  // or whatever the current name is

	void add(Element e) { }
	void add(Comment c) { }
	void add(ProcessingInstruction pi) { }
	void add(String s) { }
	void addAll(List stuff) { }

	boolean remove(Element e) { }
	boolean remove(Comment c) { }
	boolean remove(ProcessingInstruction pi) { }
	void removeAll(List stuff) { }
	void clear() { }

While "get(String name)" may not appear very clear, it makes no sense to get a
Comment or a ProcessingInstruction by name anyway, so I think it is OK. 

However :-) the sticky point again is how to get all the child elements? Here
I have to say I prefer getElements()

So, my first choice would be:

	get
	getElements
	getMixedContent
	remove() - overloaded
	add() - overloaded
	
--

Patrick Dowler
Canadian Astronomy Data Centre