commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stephen Colebourne <>
Subject Re: [all][math] Help wanted with exceptions API design
Date Tue, 01 Feb 2011 11:38:04 GMT
I can give some feedback based on JSR-310.

I have a small hierarchy of exceptions that attempts to capture some
key problems that may occur. The problem I found was that as I
refactored code, the exceptions listed in Javadoc quickly became
inaccurate. As a result, I've started converting many exceptions to
the parent CalendricalException. If a method returns a subclasses of
CalEx then thats fine and provides more info. But documenting it as
returning the subclass is way too much work for limited gain.

For [math], simply documenting MathException is sufficient.
MathRuntimeException, is unecessary as a name when all exceptions are
runtime (the correct decision).

More generally, an obsession with having every piece of exception data
available via a variable is generally unhelpful. It simply leads to
large unmaintainable hierarchies and arguments like this one. It is
very rare to need the data. [math] is suffering because of localizing
exception, which IMO is a big mistake and the cause of a lot of the

In general, exceptions are for two purposes - info on failure and to
trap for retry.

Info on failure simply needs a good message in English. No data is
required, although important (certainly not all!) pieces might be

Trap for retry errors should be rare if present at all. I would much
prefer to see a proper result object which everyone is forced to check
to describe the success or failure of something that might be retried.

In general though, the main advice is to keep it simple. People rarely
use exception hierarchies. Mostly they want the message to be readable
to diagnose the problem in a stack trace.

Finally, use the standard exceptions and patterns. IllegalArgumentEx
for example (which won't extend from MathEx, so does require separate
documentation). As in the guide, IllArgEx is for preconditions
mentioned in Javadoc or reasonably related to them, not general
calculation issues.

Similarly, look at the standard JDK executor framework
(ExecutionException) to understand the necessity to wrap callbacks.


On 1 February 2011 00:38, Phil Steitz <> wrote:
> We are in process of redesigning our exceptions hierarchy in [math]
> and we could use some input / perspective from other Commons
> community members.  Thanks in advance for your feedback and perspective.
> The most recent attempt at agreeing on design principles is [1] and
> I have tried to document the points of agreement in a section that I
> just added to the [math] Developer's Guide [2] (it will take a few
> hours for this to make it to the live site.  The source xdoc is in
> trunk/src/site/xdoc/developers.xml)
> The JIRA issue [3] referenced in [1] calls out a specific point on
> which we are trying to gain consensus in a specific example.
> The currently defined exceptions in [math] can be found in the
> top-level package and .exceptions.  Those in the top-level have at
> this point been deprecated.
> Thanks!
> Phil
> [1]
> [2]
> [3]
> ---------------------------------------------------------------------
> To unsubscribe, e-mail:
> For additional commands, e-mail:

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message