[jdom-interest] insertChild in Element

[Rosen, Alex]

> You don't have to grab the "guts of an Element." You are grabbing a Java
> structure that is universal (a List) and operating upon it. There's
> nothing exposed about this.

The confusion is that, since you specify that actions on that List affect the Element,
the natural assumption is that you're simply handing back a reference to the Element's
internal List. This isn't the case, but it's the natural assumption, so people don't
like it.

> You're inserting an Element - by definition, you want to affect the
> internal implementation.

The problem here is the opposite assumption from before. Usually, when you ask for
information about an object, you're given a static representation of that information.
In most other APIs I've seen, if you get back a list-type data structure, changes to
that structure don't have any effect. It feels very unnatural to me to get back a List,
and then have changes to that List affect the Element. It makes sense once it's
explained, but it will have to be explained over and over (as we've seen!)

> > It seems to me that the ability to insert a child into an Element at a
> > particular location is behavior which belongs to the Element itself.  I
> > would advocate adding this capability to Element.
>
> Seeing as we haven't heard this complaint from anyone else in 6 months,
> I'm leary to add it. I think the line above is pretty simple to put in,
> and makes a lot of sense. It's most of the reason we made the list of
> children live, anyway.

Huh? Searching the archives for just the past 3 months, I found 4 different requests
for this. Well, OK, in fact I found 4 different requests for the ability to insert an
Element at a particular location, from people who didn't realize that you could do this
by manipulating the List that's returned via getChildren(). This tells me that this is
non-intuitive to many people (myself included). If this mechanism is kept as-is, it
just needs to be *prominently documented* (perhaps in the JavaDoc for both the Element
class itself, and for Element.addChild()).

--Alex