[jdom-interest] detach() [eg]

[Joseph Bowbeer]

jh writes:

> Note the Servlet API doesn't have a canGetWriter() method

I don't think a servlet request is a good model for us adopt.  A servlet
request is not very similar to a JDOM document -- in substance or use.

> I find it hard to picture a time where you don't know the state
> of a Document wrt its root.

My concern is about the impact on consumers of documents.  (XMLOutputter is
a trivial example.)

    class Consumer {
        void consume(Document doc) {
        }
    }

A defensively-written consumer will want to deal with the ISE in some
manner.  They will want to throw an exception more appropriate to *their*
context -- not an ISE.  The writers of these methods will want a
state-checking method.  Otherwise, you're forcing them to catch-rethrow.

(But we've been down this path before.  By trying to be nice, we're lowering
the quality of our API and making it harder for JDOM users to write robust
code.)


----- Original Message -----
From: "Jason Hunter" <jhunter at collab.net>
To: "Joseph Bowbeer" <jozart at csi.com>
Cc: <jdom-interest at jdom.org>
Sent: Saturday, April 28, 2001 1:40 PM
Subject: Re: [jdom-interest] detach() [eg]



Joseph Bowbeer wrote:
>
> A more serious objection is the apparent absence of a state-testing
> method. I haven't seen concrete code for the ISE Document idea
> (hint hint), but as far as I can tell, the idea is that every accessor
> except setRootElement can throw ISE and that we aren't providing
> any direct way for the user to test if the Document is in an illegal
> state.

Note the Servlet API doesn't have a canGetWriter() method, it just
throws an ISE if you call getWriter() inappropriately.

> This sounds broken to me.  To fix this, we'd either need to let
> getRootElement return null, or we'd need to add a separate state-testing
> method.  Which one should it be?  Note that if getRootElement is allowed
> to return null, then ISE has lost much of its fail-fast capability
> (right?).

I don't think we need a hasRootElement() method.  I find it hard to
picture a time where you don't know the state of a Document wrt its
root.  The use case here is that someone is harvesting the root for use
in another document.  The original document is being thrown away.  In
the off chance the old doc is still referenced and is *accidentally*
used (prob due to programmer error), the doc's going to be smart enough
to point out to the caller that it's in an illegal state.

-jh-