Mailing-List: contact dev-help@commons.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "Commons Developers List" <dev@commons.apache.org>
Received-SPF: pass (nike.apache.org: domain of sebbaz@gmail.com designates
 209.85.216.43 as permitted sender)
DomainKey-Signature: a=rsa-sha1; c=nofws;
        d=gmail.com; s=gamma;
        h=mime-version:in-reply-to:references:date:message-id:subject:from:to
         :content-type:content-transfer-encoding;
        b=wxGqMmxwagzdDNAgyovV/kW1X3XeElOlSWz45A0h8MeyfsFdJE8vSc/JtJSMqT79Yw
         hCRZqHEFlFeGBIc6HRKVysOabk6wUGiLLMmxzL4oxM3lySp2GH9xl3Uv6A2xSp0sFZPP
         2rsMlpaVo/7ky56UzCCG/F5VaThY02K7XEPw8=
MIME-Version: 1.0
In-Reply-To: <20101116231944.GL10411@dusk.harfang.homelinux.org>
References: <4CE2EEF4.2030204@free.fr>
	<20101116231944.GL10411@dusk.harfang.homelinux.org>
Date: Tue, 16 Nov 2010 23:44:44 +0000
Message-ID: <AANLkTimuDbTDCFSTf+h2sEk3qxyvFLMbPN6Y=5=3og-y@mail.gmail.com>
Subject: Re: [math] preparing smooth interface upgrade for users
From: sebb <sebbaz@gmail.com>
To: Commons Developers List <dev@commons.apache.org>
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: quoted-printable

On 16 November 2010 23:19, Gilles Sadowski <gilles@harfang.homelinux.org> w=
rote:
> Hello.
>
>> 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 {
>> =A0 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 {
>> =A0 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 ?
>
> -0

+1

>
> 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.

Won't the deprecations take care of that?

> 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." ;-)

However, deprecation warnings are a strong hint that failure is
imminent, and they may wish to prepare for the change.

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

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