[Advanced-java] Designing an Exception Heirarchy

[bgw@xxxxxxxxxxxx (Bruce G Wilson)]

I've been working with Java for a bunch of years, and C++ before that, so
I'm very comfortable with designing class heirarchies in the course of
implementing an application - inheritance, polymorphism, etc, etc.  A
problem that's confronted me in the last couple of jobs is how to design a
heirarchy of exceptions.  It's easy (well, relatively easy 8^) to design
a class heirarchy when you're picturing how your system is supposed to work.
It just seems to me to be more difficult to design a heirarchy of classes to
handle the situations where the system doesn't work as intended.

The JDK clearly employs a heirarchy of exceptions. A good example is
java.io.IOException: this is the base class for a number of exceptions in
the java.io and also the java.net package: EOFException, FileNotFoundException,
MalformedURLException, SocketException, etc.  And some of these exceptions
are specialized into other exception classes.  java.net.SocketException is
inherited by BindException, ConnectException, NoRouteToHostException.
java.io.ObjectStreamException is the base class for 7 other exceptions, all
related to object serialization (NotSerializableException, for instance).

There have been some occasions recently when I've been designing and
implementing a large server side application where I wanted to report errors
from various levels in the system by throwing exceptions.  I just couldn't
figure out a good way to begin to analyze, at the design phase, what the
general classes of exceptions should be.

What I ended up doing is creating a general class of exception, using it
everywhere, and then refactoring later, replacing that general exception
with more specific ones.  The more specific exceptions carry more information
about the nature of the situation that cause the exception to arise.  I tend
to add properties (getter methods) to the exception to return instances of the
data near where the exception occurred (for example, if some instance of data
could not be parsed, I have properties that name the data that could not be
parsed and that return the unparseable string).

I'm looking for ideas on how to improve the process of designing exceptions
like this, in particular, some way of trying to analyze what the general kinds
of exceptions are at the design phase.  Does anyone have any thoughts ?  Any
good papers or books that you've read that cover these topics ?

What is the equivalent of CRC cards for designing exceptions ?

What's the best strategy for declaring exceptions in a "throws" clause: just
the general "base" exception, or the exact, subclassed exception(s) that get
thrown ?  Keeping just the base exception declaration allows me to refactor
more easily: the method still throws that kind of exception, it's just a
specialization now.  But the contract between caller and calling code isn't
as clear any longer.  Many of the read() methods in java.io.DataInputStream,
for example, declare that they throw both IOException and EOFException, even
though EOFException extends IOException.  I seem to recall from some socket
programming that I was doing a while back that some methods of the java.net
classes declared that they threw IOException, but I was actually catching
some subclass of that, and at one point I had to catch some of those
subclassed exceptions and handle them in different ways (I forget the exact
situation right now).

Thanks in advance,

Bruce