commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Phil Steitz <>
Subject Re: [Math] FunctionEvaluationException in UnivariateRealFunction
Date Sun, 07 Nov 2010 21:20:21 GMT
On 11/5/10 5:39 PM, Gilles Sadowski wrote:
> Hello.
>> [...]
> Of course, I didn't overlook that you just ask for a
>    @throws FunctionEvaluationException when the evaluation failed.
> Javadoc comment.

> I'm just reluctant to publicize a guideline that is not adhered to in CM!
> Whenever a method is passed an argument that doesn't fulfill pre-conditions,
> it throws an "IllegalArgumentException". But "FunctionEvaluationException"
> is not a subclass of "IllegalArgumentException". Users who are passed a
> "UnivariateRealFunction" instance should not rely that catching
> "FunctionEvaluationException" will work in most cases!
> So, should the Javadoc in fact be
>    @throws IllegalArgumentException when the evaluation failed because
>    of an invalid argument.
>    @throws FunctionEvaluationException when the evaluation failed for any
>    other reason.
> ?
In the cases where we know both are possible, yes, including as much 
context- or algorithm-specific information as possible in each 
throws clause.

I somewhat reluctantly agreed to dispense with checked exceptions, 
but we absolutely need to document the unchecked exceptions that we 
know can be thrown by [math].  The examples that Luc refers to above 
and the usefulness in general of the FunctionEvaluationException are 
consequences of the layered structure of the library and inclusion 
of user code "sandwiched" as he describes it within the [math] 
> Then, how do you extend your guidelines to make it clear when to use one or
> the other?

+1 - here is an idea that can likely be improved:

IllegalArgumentException - thrown when the activated method itself 
can ascertain that preconditions specified in the API expressed at 
the level of the activated method have been violated.  In the vast 
majority of cases where [math] throws IllegalArgumentException, it 
is the result of argument checking of actual parameters immediately 
passed to a method.

FunctionEvaluationException - may be advertised by a method that may 
encounter errors evaluating a function.  This *should* be thrown 
only in circumstances where at the level of the activated function 
IllegalArgumentException is not appropriate and it *should* indicate 
that while formal preconditions of the method have not been 
violated, an irrecoverable error has occurred evaluating a function 
at some (usually lower) level of the call stack.  Convergence 
failures, runtime exceptions (even IllegalArgumentExceptions) in 
user code or lower level methods can cause (and should be wrapped 
in) FunctionEvaluationExceptions.

> You could write a document that would explain how good it would be if all
> programs were using the same exceptions. But I must point out that CM isn't
> a good example, with its policy of no dependencies. Why would anyone depend
> on CM just for the sake of using CM exceptions?

I think you are missing the point here - our APIs can encourage 
consistent use of exceptions by user code that uses and/or 
integrates with [math].

These are the kinds of things we need to talk about in refactoring 
exceptions.  Our API - including all advertised exceptions - needs 
to help users understand what we - and they - are doing, not just 
minimize the amount of code they need to write or simplify our lives 
as maintainers.  This is especially true of the more complex 
algorithms and frameworks where user code plugs into [math].

> Best regards,
> Gilles
> ---------------------------------------------------------------------
> To unsubscribe, e-mail:
> For additional commands, e-mail:

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

View raw message