[jdom-interest] detach() [eg]

[philip.nelson at omniresources.com]

> On Mon, Apr 23, 2001 at 10:40:19AM -0400, Elliotte Rusty Harold wrote:
> >At 10:48 PM -0400 4/22/01, Scott Means wrote:
> >>It seems to me that one of Jason's major objections is the 
> need to catch a
> >>random new exception anytime he wants to use the .detach() 
> method, e.g.:
> >>
> >>>  >} catch (IllegalXXXException e) {
> 
> Note that the try/catch is unnecessary in any event if the exception
> thrown is one of the suggested IllegalThisOrThatExceptions 
> (they're all
> runtimes).

Sure.  My problem is that if you follow Joe's idea and use null instead, in
*that* case you get a NullPointerException.  I would rather have the
unchecked IllegalStateException (I think Joe is right about that) that says
"you don't have a root element bozo", meaning me of course.  In both cases,
you can just call detach without checking for exceptions so long as your
code is well tested.

> 
> >OK. Here's another proposal that comes from still another direction, 
> >and avoids all exceptions. Suppose instead of letting a child detach 
> >itself from its parent we let the parent element detach the 
> child. In 
> >other words the signature of the detach() method would now look 
> >something like this:
> >
> >public void detach(Element toBeDetached)
> >public void detach(Comment toBeDetached)
> >public void detach(String toBeDetached)
> 
> Isn't this one a problem?

Yeah, Strings wouldn't get detached, would they?  That content isn't
attached to a parent.

> 
> >public void detach(ProcessingInstruction toBeDetached)
> >public void detach(Entity toBeDetached)
> >
> >We would simply not give Document a detach() method so the root 
> >element could not be detached and no exceptions would ever be thrown 
> >by detach()?  In fact when this discussion popped up this is how I 
> >thought the detach() method actually worked, and I was a little 
> >surprised when the JavaDoc told me otherwise.

<snip>

I'm not that interested in the String vs Text node argument at this point
;^)

> I still think Elliotte's idea here is preferable (I like the semantics
> better anyway: detach(thatThing) instead of me.detach()), 

Actually, so do I.  As least there is no hidden side effects.  The change
would be fairly minor too because you would only have to do it where there
are possilbe child elements.  But swaying the argument about the Document
detaching the root element has been quietly passed on by Elliotte.  I guess
you would have to clone the root element to copy it exactly somewhere else.
And because you are explicitly working with the document at the time, at
least you know you should do something.  But there is still the use case of
not caring at all what happens to the document after you detach.  And in
large documents, you would not want the memory hit of cloning the root
element with all the content, just to throw it away.  No, I still think
Document.detach(Element) makes sense.

So, with a detach on document, you don't have the *unanticipated* null root
element.  IllegalStateException vs NullPointerException?  I still say
IllegalStateException and only if getRootElement is called.
 
> Could we dispense with .detach() altogether?  Can't you call
> setParent(null)?

no, it's protected