commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Luc Maisonobe <Luc.Maison...@free.fr>
Subject [math] preparing smooth interface upgrade for users
Date Tue, 16 Nov 2010 20:52:04 GMT
Hello all,

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 ?

best regards,
Luc

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org


Mime
View raw message