[jdom-interest] detach() [eg]

[Jason Hunter]

> It seems to me we have a growing consensus here.

I think you're overly optimistic.

> 1 - detach becomes the responsibility of the parent and takes an argument of
> the content to be detached.
> 2 - detaching a root element from document will put the document into an
> illegal state and the IllegalStateException will be thrown by getRootElement
> and getMixedContent
> 3 - after the root element is detached, it will internally be set to null.

Not quite.  Here's where I'm at:

A detach() on a root element removes the root from the document.  This
leaves the document in a state without a root (signified not by a null
but by the fact there's just no Element in its content list; in the
latest CVS there's no "root" variable anymore).  Any later call to
getRootElement() or getMixedContent() on the Document without a root
element throws an IllegalStateException.  If the user adds a root first,
the ISE is avoided.  If the user doesn't touch the document after the
detach, the ISE is avoided.  With this approach we also have the option
of having a Document() constructor which will create a doc also without
a root.  This is handy for SAXBuilder.  I'm not sure I want to go that
far though.

The summary of this approach is we still enforce well-formedness, but on
the issue of each doc having a root we enforce it lazily rather than
aggressively.  I lean this way because with a root.detach() I think it's
extremely likely that people will discard the detaching document and not
want to be burdened with figuring out how to manage a special case
detach first before stealing the doc's root.  I want the story simple
for newbies: use elt.detach() to move and elt.clone() to copy.

This approach is somewhat similar to the collections
ConcurrentModificationException where they don't prevent the "bad thing"
from happening, but do let you know before it affects you.

To rebut Elliotte's argument that ISE is just for threads, you can look
at the Servlet API where getWriter() throws an ISE if getOutputStream()
was already called, and vice versa.

> So, can I go back to coding again?

Are you coding on JDOM?  I have a pile of stuff!

-jh-