[jdom-interest] deprecated methods and other suggestions

[Alex Rosen]

"Convenience methods is one of Java's most important features."

I don't know about that... It's important to have the right amount of
convenience methods, not too many or too few. If something's not very
common, and/or is only a couple of lines of code, I don't think it needs
a convenience method. Every method you add is one more that the user has
to wade through to find the one they're actually looking for. I hate
classes with dozens of methods that make it hard to find the one you're
looking for. Element's already got a LOT of methods. Of course, my
crucial convenience method that I use all the time might be something
that you'd never have a use for, so how you figure out which ones to
include isn't clear.

Also remember that in JDOM "children" means only elements, "content"
means all children. (Which is really bad IMO but too late to change.) Do
you really want to remove only child Elements but leave other content?
That doesn't sound like a very common need, I don't mind if it's 2
method calls instead of one. Wanting to remove all content seems a lot
more common. I don't know if it's common enough to warrant its own
method, just to save one extra line of code. (And a little bit of
efficiency.) Same with hasChildren() or hasContent().

I can see the use if a method that retrieves a child or children no
matter how far down the tree they are, especially since DOM has this and
people are used to it. The disadvantage is that we already have 4
getChild/getChildren methods, so we'd have to add 4 more. Don't know if
it's worth it or not.

Alex

>>> Daniel Tofan <dtofan at mail.chem.sunysb.edu> 5/1/2003 12:48:52 PM
>>>
  I have been using jdom b8 for a while and now I just got the b9 
version. I was unpleasantly surprised by a few changes. I had switched

from DOM to jdom for its ease of use and convenience. I now see that 
this convenience is going away and I'm wondering why. Here are my
concerns:

First, I believe that deprecating removeChildren() in Element is not a

good idea. Removing all children from an element now requires 2 method

calls and the intermediate List object, instead of just one method
call.

Same goes for hasChildren(). It makes perfect sense to check whether an

Element has children with this method; why the extra burden of
returning 
a List and checking its size?

Also, there are some features that would be quite useful (and/or 
convenient) and that are not present in jdom. One would be a method 
getFirstChild() in Element, which would return the first child. Again,
I 
see no reason why users should be forced to go through the List
returned 
by getChildren() to find what they need. Convenience methods is one of

Java's most important features.

Another one would be a method to retrieve a child of an Element with a

given name, no matter what depth it's at. For example, an element
called 
"mat" could be found in structures such as:
    <a>
        <mat/>
    </a>
or
    <a>
        <b>
            <c>
                <mat/>
            </c>
        </b>
    </a>
In order to get the <mat/> element from however deep it resides, I had

to implement the method:
Element dig(Element from, String target) , which returns the first 
occurrence of a child called "target" of the element "from", no matter

the depth. I am making heavy use of this method because I am not 
interested in any children above the <mat/> element. It would be
helpful 
if such a method existed in jdom. I would provide the code if the
method 
was accepted for inclusion.

Other methods that I find essential for my work and might benefit users

if they were available in Element:
    getSiblings() - would return all the siblings of an element
directly
    getSameNameSiblings() - as above, but only for siblings with the 
same name
    getChild(String regex) and getChildren(String regex) to retrieve
all 
children that match a regular expression, not just a fixed name

I have appreciated the flexibility of jdom over other APIs, but I would

like to see it provide more convenience for the user, which should 
definitely make it the API of choice for xml processing.

Cheers,
Daniel