Skip to Content.
Sympa Menu

xom-interest - Re: [XOM-interest] design principles

xom-interest AT lists.ibiblio.org

Subject: XOM API for Processing XML with Java

List archive

Chronological Thread  
  • From: Elliotte Rusty Harold <elharo AT metalab.unc.edu>
  • To: "Michael McEniry" <mmceniry AT itsc.uah.edu>, <xom-interest AT lists.ibiblio.org>
  • Subject: Re: [XOM-interest] design principles
  • Date: Fri, 20 Sep 2002 17:39:31 -0400

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/ |
+----------------------------------+---------------------------------+




Archive powered by MHonArc 2.6.24.

Top of Page