<br><br><div class="gmail_quote">2012/1/18 Rolf Lear <span dir="ltr"><<a href="mailto:jdom@tuis.net" target="_blank">jdom@tuis.net</a>></span><br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">


Hi all.<br>
<br>
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.<br>



<br>
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.<br>



<br>
Certainly it is 'ugly' to have to try/catch even the simplest XPath expressions:<br>
<br>
List<?> nodes = null;<br>
try {<br>
  nodes = XPath.selectNodes(document, "//tag");<br>
} catch (JDOMException e) {<br>
  // handle it somehow<br>
  ...<br>
}<br>
// do something with nodes.<br>
<br>
This would all be much simpler if the code throws a RuntimeException instead:<br>
<br>
List<?> nodes = XPath.selectNodes(document, "//tag");<br>
<br>
<br>
<br>
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):<br>
1. SAXOutputter throws JDOMExcepion on all it's calls because it traps SAXException from the output target: <a href="http://jdom.org/docs/apidocs/org/jdom/output/SAXOutputter.html#output%28org.jdom.Document%29" target="_blank">http://jdom.org/docs/apidocs/org/jdom/output/SAXOutputter.html#output%28org.jdom.Document%29</a><br>



2. DOMOutputter throws JDOMException to wrap ParserConfigurationException from Java's DocumentBuilder.<br>
3. XSLTransform throws a subclass of JDOMException.<br>
<br>
Interestingly, XMLOutputter throws IOException, but not JDOMException.<br>
<br>
<br>
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.<br>



<br>
<br>
There are a number issues at stake here though:<br>
<br>
1. In JDOM the JDOMException is specified ( <a href="http://jdom.org/docs/apidocs/org/jdom/JDOMException.html" target="_blank">http://jdom.org/docs/apidocs/org/jdom/JDOMException.html</a> ) 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?<br>



<br>
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?<br>



<br>
3. It creates a major backward-compatibility issue to remove the 'throws JDOMException' from methods. Existing code that does:<br>
<br>
try {<br>
  nodes = XPath.selectNodes(document, "//tag");<br>
} catch (JDOMException jde) {<br>
  // handle it somehow<br>
  ...<br>
}<br>
<br>
Fails to compile with:<br>
<br>
    [javac] ....\src\java\org\jdom2\test\cases\xpath\AbstractTestXPath.java:595: exception org.jdom2.JDOMException is never thrown in body of corresponding try statement<br>
    [javac]             } catch (JDOMException jde) {<br>
    [javac]               ^<br>
    [javac] 1 error<br>
<br>
<br>
<br>
<br>
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.<br>



<br>
Backward compatibility is 'screwed' though, but somewhat mitigated by the fact that 'old' code can be modified from:<br>
<br>
   ...<br>
} catch (JDOMException jde) {<br>
   ...<br>
<br>
<br>
to<br>
<br>
   ...<br>
} catch (JDOMRuntimeException jde) {<br>
   ...<br>
<br>
Alternatively, depending on the actual exception handling, the try/catch can be completely removed and handling can be cascaded up to a higher point....<br>
<br>
<br>
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.<br>



<br>
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'.<br>



<br>
<br>
<br>
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.<br>
<br>
<br>
Would love some thoughts on this....<br>
<br> Rolf</blockquote><div><br></div><div>What about a JDOMXPathException as a subclass of JDOMException?</div><div>The code above would still work.</div><div>You could still subclass JODMException from RuntimeException fi really wanted.</div>

<div>Personally I rather like unchecked exceptions but would love a hint from the compiler/IDE.</div>
<div>Runtime exceptions can be quite nice but it depends very much on the use case. I had once a dependency injection framework which worked great with them, but all the checks needed to be done only once at startup and if failed to program schould startuo at all, so this was a special case...</div>


<div><br></div><div>What I personally prefer is that an API, offers a special exception to deal with, in this case JDOMException. This way you can embed all the JDOM related code in one try{...}catch(JDOMException) {} block</div>

<div>JDOMException could still use some more subclasses though.<br></div><div><br></div><div>Victor</div></div>