commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Phil Steitz <>
Subject Re: [all][math] Help wanted with exceptions API design
Date Wed, 02 Feb 2011 06:04:34 GMT
On 2/1/11 6:38 AM, Stephen Colebourne wrote:
> 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
> issues.
I am not sure really that the localization framework is the cause of
significant issues for us.  It does force us to maintain the
messages and to maintain a top-level exception;  but the problems we
are having getting to consensus on design really have more to do
with a) high-level vs low-level exception concepts and b) how much
we can depend on messages (localized or not) to convey exception
context and specialization information.  We have been maintaining
the messages for 2+ years now and this has not been a big deal, IMO.
> 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
> captured.
I agree with this; though the right data needs to be there.  A
canonical example is ArrayIndexOutOfBoundsException reporting the
bad index in the message.  The message should include a full
statement of the failure *at the level of abstraction appropriate to
the exception itself*
> 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.
"Retry" is not in general meaningful for our stuff, though in a
small number of cases, "try a different algorithm" or "try a
different starting point" , "adjust parameters and retry"  or
"return a special value"  (all of which [math] code does internally
at different places) can be reasonable. 

What we report back to the application using [math] is that one of
the following kinds of bad things has happened

a) they have violated preconditions - they get
MathIllegalArgumentException (same semantics as anywhere else)
b) they have not violated preconditions, but a numerical problem has
occurred (while not violating stated preconditions, their problem is
not in the effective domain of the algorithm they asked [math] to
c) they have hit a bug in [math]

Of course, we have no way of distinguishing b) and c) and a fair
amount of our JIRA work really comes down to viewing b) problems as
c) problems (increasing the effective domains of our implementations).
> 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.
Agreed.  This is why we had a very flat hierarchy through version
2.0 of [math].  Where we are having trouble gaining consensus is how
to represent specializing context information in our exceptions and
what abstractions to use to represent the shallow hierarchy that we
aim to build.  For example, in 2.0, we have a ConvergenceException,
representing the commonly occurring scenario of type b) above where
an iterative algorithm has failed to converge.  This exception is
often caught and wrapped or recovered from internally in [math].  It
has a subclass, MaxEvaluationsExceededException to represent the
common convergence failure suggested by its name.  I personally
think we should keep this exception in 3.0.  Gilles thinks that we
should replace it by more granular exceptions like
"MaxCountExceeded" or "NotFiniteNumberException" (another reason
that a sequence can fail to converge) that have nothing to do with
convergence.  We are similarly at odds regarding
"FunctionEvaluationException" a top-level exception indicating that
an error has occurred evaluating a function. 
> 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.
Thanks, Stephen!


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

View raw message