[jdom-interest] detach() [eg]

Patrick Dowler patrick.dowler at nrc.ca
Wed Apr 25 12:13:04 PDT 2001

Here a few more cents for the pot...

On 25 April 2001 11:00, Jason Hunter wrote:
> Brett McLaughlin wrote:
> > I'm with Elliotte that detach should not be on the Element, but on the
> > Element's parent.
> We already have Element.removeContent().  If you're suggesting a new
> method Document.detach(Element) or Document.removeContent(Element) then
> it's no better than status quo because that call would still allow
> non-well-formed documents.
> Or is your argument that detach() should go away, that
> Element.removeContent() should remain, and that Document should thus
> have no way to detach its root short of the programmer substituting a
> new root in place of the old with setRootElement()?  Ugh.

There appear to be 2 issues here, so I'll try the easier one first.

** someEl.detach()

In the non-root-element case, it seems like a reasonable move to deprecate detach()
and simpify the API. It is just short-hand for "el.getParent().removeContent( el )" anyway 
(aside from the return value). Moving an element is:

   el.getParent().removeContent( el ); // ignoring boolean return
   newParent.addContent( el );

instead of

   newParent.addContent( el.detach() );

Since Comment, ProcessingInstruction, etc could also be moved and are they 
currently handled as above (ie. removeContent followed by addContent() ).

Basically, by putting detaching in the parent instead of the child, one avoids
having to deal with the difference between root and non-root elements in 
the Element class (good) and puts the responsibility where it belongs (also good).

** rootEl.detach()

This is the case where we are discussing whether or not it is worth always
enforcing well-formedness. Maybe in future we won't be able to, but for now...

Personally, is it really all that bad to use setRootElement() instead of detach()?

   Element oldRoot = doc.getRootElement();
   doc.setRootElement( new Element("junk") );

So, you have to create a single Element that is otherwise wasted. Yes, you have 
a meaningless but well-formed document (at very little cost) and yes, you have 
a placeholder, but at least it is one put there by the programmer rather than by 
the JDOM implementation. 

At worst, we use setRootElement() and let the programmer explicitly set it to null
to detach, or we could add a method to Document, say:

    Element removeRootElement() { ... }

that explicitly put the Document into the illegal state. I just don't like a method call
on Element to put another object (the parent Document) into an illegal state. If we
are to have a Document in an illegal state, this should be done with a Document
method directly.

Note: programmers absolutely MUST know that Document.setRootElement() 
detaches (and potentially discards) the old root element... 

Patrick Dowler
Canadian Astronomy Data Centre
National Research Council
Victoria, BC

More information about the jdom-interest mailing list