Re: JDOM2 and Runtime Exceptions

There has been a long-standing debate about checked vs. unchecked
exceptions in Java, but I think checked exceptions are a good part of Java,
and I like the guidelines in Effective Java.  Unless someone has a
convincing argument that JDOM got exceptions all wrong, I think it's best
not to change this aspect too much, especially if it will break backward
compatibility.

So I think I agree with where your mind is at.

On Wed, Jan 18, 2012 at 5:03 PM, Rolf Lear wrote:

> Hi all.
>
> This issue has been nagging at me. I finally pulled out my copy of
> 'Effective Java'.
>
> Quoting some sections (Item 58):
>
> > Use checked exceptions for conditions from which the caller can
> reasonably be expected to recover. Each checked exception ... is therefore
> a potent indication to the API user that the associated condition is a
> possible outcome. [this] presents a mandate [for the API user] to recover
> from the condition.
>
> > If a program throws an unchecked exception ... it is generally the case
> that recovery is impossible and continued execution would do more harm than
> good. Use runtime exceptions to indicate programming errors. The great
> majority of runtime exceptions indicate precondition violations.
> Precondition violation is simply a failure by the caller to adhere to the
> contract established by the API specification.
>
>
> Putting the logic together like the above makes sense. It makes sense that
> a 'null' XPath expression is a 'precondition violation', and hence a
> NullPointerException, and it also makes sense that an invalid XPath
> expression is something that the caller can reasonably be expected to
> recover from, and should be checked - even if it is inconvenient
> sometimes...
>
> Thus, I think I have it settled in my mind that changing to an unchecked
> exception is wrong (even if the code looks a lot prettier).
>
> I think I may still differentiate between an XPath 'compile' exception,
> and an XPath 'evaluation' Exception instead of using a blanket
> JDOMException. Psychologically that makes it an 'XPath' problem, not a JDOM
> problem.
>
> Rolf
>
>
>
>
> On 17/01/2012 10:31 PM, Rolf Lear wrote:
>
>> Hi all.
>>
>> Recent discussions have highlighted the area of how JDOM handles some
>> exceptions. In particular the context was XPath expressions. JDOM specifies
>> (and 'always' has specified) that XPath throws JDOMException in the event
>> of a failure on XPath. This has been 'questioned' from the perspective that
>> this would not be the fault of JDOM if the XPath expression failed to
>> compile, or evaluate.
>>
>> Exceptions that are outside the control of the programmer, like
>> IOException, should be thrown and caught, but an illegal XPath is more of a
>> bug/programming error than an Exception, and hence should be treated more
>> like a NullPointerException, IllegalArgumentException,
>> IndexOutOfBoundsException, etc.
>>
>> Certainly it is 'ugly' to have to try/catch even the simplest XPath
>> expressions:
>>
>> List<?> nodes = null;
>> try {
>>  nodes = XPath.selectNodes(document, "//tag");
>> } catch (JDOMException e) {
>>  // handle it somehow
>>  ...
>> }
>> // do something with nodes.
>>
>> This would all be much simpler if the code throws a RuntimeException
>> instead:
>>
>> List<?> nodes = XPath.selectNodes(document, "//tag");
>>
>>
>>
>> So, having used XPath as one example, I can then extrapolate the issue in
>> to other general areas (sticking with concepts that are 'old' - in JDOM as
>> well as JDOM2 - JDOM2 has additional areas of concern):
>> 1. SAXOutputter throws JDOMExcepion on all it's calls because it traps
>> SAXException from the output target: http://jdom.org/docs/apidocs/**
>> org/jdom/output/SAXOutputter.**html#output%28org.jdom.**Document%29<http://jdom.org/docs/apidocs/org/jdom/output/SAXOutputter.html#output%28org.jdom.Document%29>
>> 2. DOMOutputter throws JDOMException to wrap ParserConfigurationException
>> from Java's DocumentBuilder.
>> 3. XSLTransform throws a subclass of JDOMException.
>>
>> Interestingly, XMLOutputter throws IOException, but not JDOMException.
>>
>>
>> Taking the issue to an abstract level, there are a number of places where
>> JDOM throws the checked exception JDOMException, and that exception
>> requires cumbersome handling in situations where unchecked exceptions would
>> (potentially) be a better choice.
>>
>>
>> There are a number issues at stake here though:
>>
>> 1. In JDOM the JDOMException is specified ( http://jdom.org/docs/apidocs/
>> **org/jdom/JDOMException.html<http://jdom.org/docs/apidocs/org/jdom/JDOMException.html>) as being the 'top level Exception JDOM classes can throw'. But that's
>> already *not* true. We have had all sorts of runtime exceptions thrown from
>> various classes like 'Element' which throws IlleglNameException from it's
>> constructor... So, should JDOMException be redefined to be JDOM-specific
>> problems only?
>>
>> 2. Where is the 'line'? Should SAXOutputter throw SAXException instead of
>> JDOMException (like XMLOutputter throws IOException not JDOMException)?
>> Should SAXOutputter throw some new RuntimeException instead? How could the
>> 'system' be described so that this inconsistency of exceptions is better
>> controlled?
>>
>> 3. It creates a major backward-compatibility issue to remove the 'throws
>> JDOMException' from methods. Existing code that does:
>>
>> try {
>>  nodes = XPath.selectNodes(document, "//tag");
>> } catch (JDOMException jde) {
>>  // handle it somehow
>>  ...
>> }
>>
>> Fails to compile with:
>>
>>    [javac] ....\src\java\org\jdom2\test\**cases\xpath\AbstractTestXPath.*
>> *java:595: exception org.jdom2.JDOMException is never thrown in body of
>> corresponding try statement
>>    [javac]         } catch (JDOMException jde) {
>>    [javac]           ^
>>    [javac] 1 error
>>
>>
>>
>>
>> I have been playing with the code anyway, and I like the looks of the
>> results of replacing 'strategic' JDOMExceptions with a runtime Exception.
>> For example, I created a new unchecked JDOMRuntimeException class. From
>> this class I created two subclasses: XPathCompileException and
>> XPathEvaluationException. I made all the code 'work' nicely with these
>> exceptions and the code looks very clean.
>>
>> Backward compatibility is 'screwed' though, but somewhat mitigated by the
>> fact that 'old' code can be modified from:
>>
>>   ...
>> } catch (JDOMException jde) {
>>   ...
>>
>>
>> to
>>
>>   ...
>> } catch (JDOMRuntimeException jde) {
>>   ...
>>
>> Alternatively, depending on the actual exception handling, the try/catch
>> can be completely removed and handling can be cascaded up to a higher
>> point....
>>
>>
>> Apart from renaming all the packages to org.jdom2, this would be the most
>> significant migration problem for any users of JDOM/JDOM2. Documenting it
>> as a migration issue should be relatively easy, but the fix would not be a
>> pure search/replace, but the exceptions would have to be identified and
>> fixed individually.
>>
>> Admittedly in a tool like eclipse, it is quite easy to put 'Runtime' in
>> your copy/paste buffer, and go from one compile problem to the next simply
>> looking for the 'unreachable code' problem and adding the 'Runtime' to the
>> middle of 'JDOMException'.
>>
>>
>>
>> Sorry for the long mail, but this is a 'feature' which could make JDOM2
>> much easier to work with, but would certainly make a migration from JDOM
>> more complicated.
>>
>>
>> Would love some thoughts on this....
>>
>> Rolf
>>
>

_______________________________________________
To control your jdom-interest membership:
http://www.jdom.org/mailman/options/jdom-interest/[email protected]