On 1 February 2011 11:20, Gilles Sadowski <gil...@harfang.homelinux.org> wrote: > Hi. > >> Added section on Exceptions. > > I agree with the explanations; however I think that we should add a paragraph > (see below). > >> Modified: >> 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/xdoc/developers.xml?rev=1065874&r1=1065873&r2=1065874&view=diff >> ============================================================================== >> --- commons/proper/math/trunk/src/site/xdoc/developers.xml (original) >> +++ commons/proper/math/trunk/src/site/xdoc/developers.xml Tue Feb 1 >> 00:23:48 2011 >> @@ -183,6 +183,50 @@ >> Guide.</li> >> </ul> >> </subsection> >> + <subsection name='Exceptions'> >> + <ul> >> + <li> >> + Exceptions generated by Commons Math are all unchecked.</li> >> + <li> >> + All public methods advertise all exceptions that they can generate. >> + Exceptions <i>must</i> be documented in both javadoc and method >> signatures >> + and the documentation in the javadoc <i>must</i> include full >> description >> + of the conditions under which exceptions are thrown.</li> >> + <li> >> + All exceptions inherit from the base class, MathRuntimeException.</li> >> + <li> >> + Methods <i>should</i> fully specify parameter preconditions required >> for >> + successful activation. When preconditions are violated, a >> + MathIllegalArgumentException should be thrown. Subclasses of >> + MathIllegalArgumentException may be used to represent common parameter >> + contract violations (for example, NoBracketingException). Exception >> + messages <i>must</i> contain sufficient information on parameter >> values to >> + determine the exact precondition failure.</li> >> + <li> >> + Exceptions generated by Commons Math make sense without knowing >> + implementation details other than those stated in the public API. >> + For example, a NoBracketingException makes sense thrown by a solver >> that >> + has a precondition requiring that initial points bracket a root. This >> + exception does not make sense, however, thrown by an inverse >> cumulative >> + probability estimator.</li> >> + <li> >> + MathIllegalArgumentException should only be thrown in situations >> + where preconditions can be exhaustively provided so that what >> arguments >> + are "illegal" can be specified fully to the caller. Domain-specific >> + exceptions need to be defined for cases where failures cannot be >> + attributed to parameter precondition violation. For example, the exact >> + domain of successful activation of a solver or quadrature method may >> be >> + impossible to specify because of numerical properties of the method. >> + If a solver fails to find a root or a quadrature method fails to >> converge >> + for a given set of parameters, <i>unless those parameters violate the >> + advertised preconditions</i> it is not appropriate to throw >> + MathIllegalArgumentException.</li> > > If the failure results from an exception thrown by user code (e.g. an > exception is thrown while a solver is evaluating a user-defined function), > the 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? >> + <li> >> + State information included in exception messages <i>must</i> be >> available >> + in exception properties - i.e., successful handling or reporting of >> + Commons Math exceptions must not require parsing exception >> messages.</li> >> + </ul> >> + </subsection> > > > Gilles > > --------------------------------------------------------------------- > To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org > For additional commands, e-mail: dev-h...@commons.apache.org > > --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
