commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gilles Sadowski <>
Subject Re: [math] preparing smooth interface upgrade for users
Date Tue, 16 Nov 2010 23:19:44 GMT

> As we are changing a lot of things in 3.0, it would be interesting to
> have 2.2 help users smoothly adapt their code. Many exceptions have/will
> be changed and some of them are used in public interfaces users have to
> implement. Typical examples are FirstOrderDifferentialEquations and the
> associated DerivativeException, or UnivariateRealFunction and
> FunctionEvaluationException.
> Discussion on MATH-425 lead to group these user-specific exception as
> one single unchecked exception: MathUserException. This choice has the
> additional advantage that when a user uses an ode solver inside an
> optimizer for example, the same exception can be used at both levels and
> an error condition occurring at very low level can be handled at top
> level without problem.
> In order to help users, I am going to use for 2.2 a transition scheme
> where the exceptions DerivativeException, FunctionEvaluationException
> and similar ones would all be deprecated and at the same time their base
> class would be changed to the new MathUserException. Then the user
> methods in the public interfaces would be declared to throw
> MathUserException. So we would change from the current design which is:
> public class DerivativeException extends MathException {...}
> public interface FirstOrderDifferentialEquations {
>   public void computeDerivatives(...) throws DerivativeException;
> }
> to a new design which would be:
> public class MathUserException extends RuntimeException {...}
> @Deprecated
> public class DerivativeException extends MathUserException {...}
> public interface FirstOrderDifferentialEquations {
>   public void computeDerivatives(...) throws MathUserException;
> }
> Then in 3.0 the deprecated exceptions would be removed (I think Gilles
> already did it).
> This is an interface change, but I think it is worth doing it and it
> does provide a sufficient level of compatibility. These interfaces are
> intended to be implemented by user, to implement their own business
> problems. Many already have implemented the interface in its 2.1
> version, probably using a DerivativeException for their error handling.
> Since DerivativeException would still be there in 2.2 and it would
> extend MathUserException, these implementations would both continue to
> work in 2.2 and new users and new implementations could already use the
> new MathUSerExceptions. The only pain for existing implementations would
> be to see warnings about the deprecated exceptions. Users would have
> some time to adapt their code and use directly MathUserException, which
> provide at least everything DerivativeException did provide up to now.
> I guess CLIRR will complain and consider this an incompatible change. It
> is true from a caller perspective since now we should expect
> MathUserExceptions rather than only DerivativeExceptions. However,
> MathUSerException is unchecked and the callers for these interfaces are
> the commons-math methods, which we will adapt. These interfaces are not
> intened to be called by user code, they are intended so that user code
> can be called by our library.
> I think this transition is the smoother path for our users. Do you think
> this change is the way to go ?


My first impression is that it is a lot of changes for 2.2 without any
benefit when users will switch to 3.0; they will still have to scan their
code for all the exceptions that will have disappeared.
In 3.0 it will clear that they *have* to do it while, in 2.2, you would
have to explain to users that it's better that they do it but that it
will still work if they don't... And they will probably say: "If it ain't
broken, I won't fix it." ;-)


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

View raw message