XOM API for Processing XML with Java

[Elliotte Rusty Harold <elharo AT metalab.unc.edu>]

At 8:19 PM -0500 9/18/02, Michael McEniry wrote:
In "XOM Design Principles" 
(<http://www.cafeconleche.org/XOM/designprinciples.xhtml>http://www.cafeconleche.org/XOM/designprinciples.xhtml), 
what do these two statements mean?

I just tossed that document up by copying and pasting bullet points 
from my slides. At the talk I elaborated one each one of course. My 
goal is to expand on each one, but it does take time. Might as well 
begin with these two.

 "Problems detectable in testing throw runtime exceptions"

I got this idea from Bruce Eckel (Does Java need Checked Exceptions?, 
http://www.mindview.net/Etc/Discussions/CheckedExceptions) and Joshua 
Bloch  (Effective Java, particularly Item 40--Use checked exceptions 
for recoverable conditions and runtime exceptions for programming 
errors--and 41--Avoid unnecessary use of checked exceptions). Bloch 
is especially clear that precondition violations should cause runtime 
exceptions should be used for. (Think IllegalArgumenteException). 
Most of the time this indicates a programming error. Thus rather than 
putting in a try-catch block to handle the exception, the programmer 
should fix the mistake that led to the programming error in the first 
place. Assuming the programmer has fixed the mistake, there's no 
reason to catch the exception because it won't be thrown. And if the 
programmer's wrong, and they haven't fixed their mistake, then they 
should learn about it as soon as possible rather than having the 
exception get lost in an empty catch block added just to make the 
compiler shut up about an uncaught exception.

Most of the runtime exceptions in XOM occur as a result of 
precondition violations, for instance passing a string to setName() 
that is not a legal XML name. This will likely happen every time the 
program is run, or every time the program executes a particular 
section of code, rather than depending on input or temporary 
conditions. This isn't always true. For instance, a GUI might ask a 
user to type in an element name and then pass that string to setName. 
Whether or not the exception is thrown would then depend on what the 
user typed. However, I think more often than not such a precondition 
violation is internal to the program, and thus should be caught by 
testing.

On the other hand, not all problems are like this. For instance, a 
ParseException is thrown when an external document is discovered to 
be malformed. There is no way to predict this in advance because the 
document is not part of the program itself (unlike the string passed 
to setName). Whether or not the exception is thrown depends 
completely on which document you're parsing, and the document may not 
even exist at compile time. There's no way to tell if it's 
well-formed or not until run time. Hence ParseException is a checked 
exception.

 "Assertions that can be turned off are pointless"

In Java 1.4 you can use a command line flag to disable assertion 
checking. However, if an assertion is violated, it's still an error, 
just one you no longer notice. Turning off assertions at runtime is 
like including airbags in a new car model during design and street 
testing, then removing them before you begin selling the cars to 
consumers. No matter how rigorously you test, the users of your 
library will encounter situations and uncover bugs you did not find 
in testing. As Rolf Howarth wrote on the on the java-dev mailing list 
back in February:

programmers love the concept of assertions so much because it's like 
having your cake and eating it. On the one hand you can kid yourself 
you're protecting yourself by testing for error conditions that you 
know you should, but on the other you're absolved from any 
responsibility if the extra checks have a performance impact because 
they won't be there in production code. Except of course people 
usually leave assertions turned on in practice, certainly once 
they've been through the loop of puzzling over obscure bug reports 
from the field and muttering "that can't happen, that assertion check 
should have picked that case up", just before their face turns white 
and they realise assertions are compiled out!

Consequently, I decided not to rely on Java's new assertion mechanism 
for precondition checking in XOM. Instead, each method that sets or 
changes some value verifies all preconditions explicitly and throws a 
runtime exception (normally a subclass of XOMException) if it detects 
a problem.

Furthermore, many methods are declared final to prevent subclasses 
from turning off this checking. Subclasses can override the various 
protected check() methods to add assertions of their own, but they 
cannot remove the assertions in the core classes.


--

+-----------------------+------------------------+-------------------+
| Elliotte Rusty Harold | elharo AT metalab.unc.edu | Writer/Programmer |
+-----------------------+------------------------+-------------------+
|          XML in a  Nutshell, 2nd Edition (O'Reilly, 2002)          |
|              http://www.cafeconleche.org/books/xian2/              |
|  http://www.amazon.com/exec/obidos/ISBN%3D0596002920/cafeaulaitA/  |
+----------------------------------+---------------------------------+
|  Read Cafe au Lait for Java News:  http://www.cafeaulait.org/      |
|  Read Cafe con Leche for XML News: http://www.cafeconleche.org/    |
+----------------------------------+---------------------------------+