[jdom-interest] detach() [eg]

[philip.nelson at omniresources.com]

> I question the use case. How many times do you want to move the root 
> element of a document? 

Very seldom I would think.  It might be one way programmers try to change
the dtd or schema of a document.

> In any case, it seems to me that all we're 
> saying is that when an element is used as the root the Document has 
> locked it and won't let it be moved without a replacement. That seems 
> perfectly reasonable to me.

yes but....

> 
> However,  this is not the problem. The problem is the phantom element 
> JDOM attaches to the root after detaching the root. That seems really 
> ugly and unexpected to me. I had no idea JDOM was even doing that 
> until this thread popped up. I think it violates the principle of 
> least surprise. There is simply no way to predict that JDOM is going 
> to create a new root element behind my back with an unknown name and 
> assign it to the Document. It seems a lot less surprising to me that 
> JDOM tosses an exception when I try to detach the root element.

It seems we mostly agree we dislike the placeholder element.  So let's make
it null.  Let's make it a one level copy of the original element.  Let's
make it a nasty warning element translated into every language known to man
:-)  Then if they try to use that element without replacing it, tell them
it's a mistake by throwing an exception.

If I really intend to dispose of the document, it would annoy me to have to
set my own bogus root element to do so.  I say throw the exception if they
try to use the phantom root element (or null element).  It is clear what the
programming error is and the other use cases, rare as they most likely are,
are simple and unchanged for all uses of element.detach().

> 
> Furthermore, the proposed semantics of detach seem quite clear: if 
> the parent is an element, then remove it from the parent. If the 
> parent is a document throw an exception. The logical distinction 
> between the two cases and the reason they behave differently is clear.

The only disagreement I have is when to throw the exception.