Re: JDOM2 and Runtime Exceptions

Hi Leigh, all

Despite my earlier mail referencing 'Effective Java', I went further in to
the book, and it then contradicts itself in "item 59" which claims "Avoid
unnecessary use of checked exceptions". It quite clearly contradicts the
"item 58".... so even Bloch is not able to clearly define a 'rule' for
checked exceptions.

This process has been an exercise of frustration. It is quite clear that
there is no clear 'right' way of doing things. There is no clear
'precedent' on how it should be done either.

Should XPath be like regex with a compile() and match() process, neither
of which throw checked exceptions? The 'similarity' between XPath and Regex
is quite convincing...

Despite my earlier claim that xpath exceptions can be 'recovered from
easily by the caller', I am not actually convinced. How do you 'recover'
from a bad expression? How do you recover from an expression that does
arithmatic with a value that is non-numeric? The argument for having
checked exceptions is very unclear, and the convenience of unchecked
exceptions is substantial.

In a 'fresh' world, if I were writing the JDOM/XPath API from scratch, I
think it would be very reasonable to throw an XPathSyntaxException for bad
XPaths just like java.util.regex.Pattern throws PatternSyntaxException.
Similarly XPathEvaluationException for issues encountered in the document.

But backward compatibility is a big issue too.

I think a big part of the API problem is because it is so closely tied to
Jaxen. Jaxen throws checked exceptions too. I am not saying that checked
exceptions are wring, but nor are they right.

On the train this morning I played again with the JDOM/XPath API. I think
I have a working solution, and I think I am more comfortable with it. It
took a while to come to, but Java already has a well defined process for
it... ;-) Deprecation.

The thrown exceptions of a method are part of it's public API. I don't
like the JDOMException thrown from XPath methods, so I am going to
deprecate them.... JDOM 1.x users will get compile warnings, not errors.
That's the compatibility problem solved.

Then, I break down the XPath in to a 'compile' and 'evaluate' step, and
make them throw unchecked exceptions that make sense for the particular
issue.

The new methods will be called 'XPath<T> compile(...)' instead of
newInstance(...), and I think I will call the new execution methods  
List<T> matchAll(context)   and   T matchFirst(context)  .

I have looked in to XPath 2.0, and by being smart with the API, and 'nice'
with the option of applying a Filter directly to the XPath, I think it is
reasonable to have the best of both worlds. With the changes as I have them
now I think plugging in a different XPath2.0 back-end should be easy when
one is available, and it will 'just work'. XPath 2.0 clearly differentiates
between 'static analysis' portion of the XPath, and the 'dynamic
evaluation' stage.

Since this is such a grey area I think someone needs to just 'decide', and
I think I will do just that.... Deprecate the old methods, keep their
signatures unchanged (including exceptions), and implement a new, clean,
unchecked, and generified set of methods.

I like the idea of XPath being similar in 'feel' to RegEx.

Time for me to get on the train again, and spend an hour playing with what
feels right.

Rolf


On Thu, 19 Jan 2012 11:35:58 -0800, Leigh L Klotz Jr
<[email protected]> wrote:
> On 01/18/2012 01:12 AM, Michael Kay wrote:
>> I don't think you'll please everyone here, but even without the 
>> compatibility implications, I'm not convinced that moving to unchecked 
>> exceptions would be an improvement.
>>
> 
> We use JDOM in our hand-written because it is a convenient, expressive 
> API, giving much of the compactness and other benefits we see from XPath

> itself and other higher-level XML interfaces such as XQuery.
> 
> However, we haven't found the JDOM1 XPath Java interface to be 
> convenient or expressive, because of the verbosity and the checked 
> exceptions, which in our case are all programming errors of one sort or 
> another.  (We don't let end users type in XPath expressions.)  Instead, 
> we use a static JDOMUtil wrapper class with methods such as 
> selectElement, selectElements, selectAttributes, selectContent, and ref 
> (leaf-node value).
> 
> So for us, the JDOM XPath API is a implementation of a way to run XPath 
> expressions over JDOM objects, and not a convenient, expressive API that

> we use to hand write Java code.
> 
> JDOM2 with the filters may offer an expressive API that would let us do 
> away with the profusion of select* utility methods, but with checked 
> exceptions it still won't be convenient, and we still won't use it
> directly.
> 
> Leaving in the checked exceptions means less migration headache for 
> other users, and since we're not going to use it directly, it doesn't 
> matter much.  Another reason we may shift away from JDOM XPath API is 
> that we're disenchanted with Jaxen as well and are hoping to find a fast

> (at runtime) way to use Saxon on JDOM from hand-written Java code.  That

> probably won't use the JDOM XPath API at all.
> 
> Leigh.
_______________________________________________
To control your jdom-interest membership:
http://www.jdom.org/mailman/options/jdom-interest/[email protected]