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.178 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=U2ub4Hu/ww8FX4XAvWqAnRozl/er1Iw/pyG2PtuukUbUiOp/G09WhT0mmiZWRGz5V9
         p6MXIx2u+eRY0rwTsnkugQcpLmYyponhCZ79SpHVlG7f2UkSX6f2K5xGr+wfoZwwbdGN
         7U6HbC7NlWruSAdLLf0LhZNtITgSY2FSNiYiM=
MIME-Version: 1.0
In-Reply-To: <20110201112031.GV22814@dusk.harfang.homelinux.org>
References: <20110201002348.DE6CE23889DA@eris.apache.org>
	<20110201112031.GV22814@dusk.harfang.homelinux.org>
Date: Tue, 1 Feb 2011 12:36:17 +0000
Message-ID: <AANLkTi=-DkPuAkKAQxRfX=3g05DEMHMpDdDJHS1Nzxre@mail.gmail.com>
Subject: Re: svn commit: r1065874 -
 /commons/proper/math/trunk/src/site/xdoc/developers.xml
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 1 February 2011 11:20, Gilles Sadowski <gilles@harfang.homelinux.org> wr=
ote:
> Hi.
>
>> Added section on Exceptions.
>
> I agree with the explanations; however I think that we should add a parag=
raph
> (see below).
>
>> Modified:
>> =A0 =A0 commons/proper/math/trunk/src/site/xdoc/developers.xml
>>
>> Modified: commons/proper/math/trunk/src/site/xdoc/developers.xml
>> URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/site/xdo=
c/developers.xml?rev=3D1065874&r1=3D1065873&r2=3D1065874&view=3Ddiff
>> =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D
>> --- commons/proper/math/trunk/src/site/xdoc/developers.xml (original)
>> +++ commons/proper/math/trunk/src/site/xdoc/developers.xml Tue Feb =A01 =
00:23:48 2011
>> @@ -183,6 +183,50 @@
>> =A0 =A0 =A0 =A0Guide.</li>
>> =A0 =A0 =A0</ul>
>> =A0 =A0 </subsection>
>> + =A0 <subsection name=3D'Exceptions'>
>> + =A0 =A0<ul>
>> + =A0 =A0 =A0<li>
>> + =A0 =A0 =A0Exceptions generated by Commons Math are all unchecked.</li=
>
>> + =A0 =A0 =A0<li>
>> + =A0 =A0 =A0All public methods advertise all exceptions that they can g=
enerate.
>> + =A0 =A0 =A0Exceptions <i>must</i> be documented in both javadoc and me=
thod signatures
>> + =A0 =A0 =A0and the documentation in the javadoc <i>must</i> include fu=
ll description
>> + =A0 =A0 =A0of the conditions under which exceptions are thrown.</li>
>> + =A0 =A0 =A0<li>
>> + =A0 =A0 =A0All exceptions inherit from the base class, MathRuntimeExce=
ption.</li>
>> + =A0 =A0 =A0<li>
>> + =A0 =A0 =A0Methods <i>should</i> fully specify parameter preconditions=
 required for
>> + =A0 =A0 =A0successful activation. =A0When preconditions are violated, =
a
>> + =A0 =A0 =A0MathIllegalArgumentException should be thrown. =A0Subclasse=
s of
>> + =A0 =A0 =A0MathIllegalArgumentException may be used to represent commo=
n parameter
>> + =A0 =A0 =A0contract violations (for example, NoBracketingException). =
=A0Exception
>> + =A0 =A0 =A0messages <i>must</i> contain sufficient information on para=
meter values to
>> + =A0 =A0 =A0determine the exact precondition failure.</li>
>> + =A0 =A0 =A0<li>
>> + =A0 =A0 =A0Exceptions generated by Commons Math make sense without kno=
wing
>> + =A0 =A0 =A0implementation details other than those stated in the publi=
c API.
>> + =A0 =A0 =A0For example, a NoBracketingException makes sense thrown by =
a solver that
>> + =A0 =A0 =A0has a precondition requiring that initial points bracket a =
root. This
>> + =A0 =A0 =A0exception does not make sense, however, thrown by an invers=
e cumulative
>> + =A0 =A0 =A0probability estimator.</li>
>> + =A0 =A0 =A0<li>
>> + =A0 =A0 =A0MathIllegalArgumentException should only be thrown in situa=
tions
>> + =A0 =A0 =A0where preconditions can be exhaustively provided so that wh=
at arguments
>> + =A0 =A0 =A0are "illegal" can be specified fully to the caller. Domain-=
specific
>> + =A0 =A0 =A0exceptions need to be defined for cases where failures cann=
ot be
>> + =A0 =A0 =A0attributed to parameter precondition violation. For example=
, the exact
>> + =A0 =A0 =A0domain of successful activation of a solver or quadrature m=
ethod may be
>> + =A0 =A0 =A0impossible to specify because of numerical properties of th=
e method.
>> + =A0 =A0 =A0If a solver fails to find a root or a quadrature method fai=
ls to converge
>> + =A0 =A0 =A0for a given set of parameters, <i>unless those parameters v=
iolate the
>> + =A0 =A0 =A0advertised preconditions</i> it is not appropriate to throw
>> + =A0 =A0 =A0MathIllegalArgumentException.</li>
>
> =A0If the failure results from an exception thrown by user code (e.g. an
> =A0exception is thrown while a solver is evaluating a user-defined functi=
on),
> =A0the Commons Math code must let it propagate without interference.

That may not be possible in general.

If the user code generates an Exception that CM already handles, how
can CM distinguish this case?


>> + =A0 =A0 =A0<li>
>> + =A0 =A0 =A0State information included in exception messages <i>must</i=
> be available
>> + =A0 =A0 =A0in exception properties - i.e., successful handling or repo=
rting of
>> + =A0 =A0 =A0Commons Math exceptions must not require parsing exception =
messages.</li>
>> + =A0 =A0 </ul>
>> + =A0 </subsection>
>
>
> 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