Single root for Exceptions WAS Re: [math] UnexpectedNegativeIntegerException

[Phil Steitz <ph...@gmail.com>]

On 8/28/12 5:36 AM, Luc Maisonobe wrote:
>  
<snip/>
> I thought I had. Perhaps this feature was set up after I gave up
> on this discussion.
>>>> It would be quite easy to change, if it would make your life easier.
>>>>
>>>> The more so that I never saw what is gained from copying the Java hierachy
>>>> (in the particular case of the exceptions): Because some exception inherits
>>>> from the Java standard one does not bring special benefits to the
>>>> application that has to catch that exception. I mean: Is there any piece of
>>>> code that would behave differently if it caught "IllegalArgumentException"
>>>> vs "IllegalStateException"? If not, it could as well be prepared to catch
>>>> a "MathRuntimeException" (and do the same thing).
>>>> [The various exception types are primarily there to discriminate between
>>>> various _problems_; but are not likely helpful to help the caller devise a
>>>> way to react to the exception once it is raised (other than acknowledge the
>>>> fact than CM could not perform the requested action).]
>>>>
>>>> In CM, the vastly overwhelming majority of exceptions are instances of
>>>> "MathIllegalArgumentException" or one of its subclasses.
>>>>
>>>> We have a "NullArgumentException" but we also agreed that it did not have to
>>>> be a subclass of the standard Java "NullPointerException". So in this case,
>>>> we already depart from the "standard". [But we also speculated that the
>>>> policy could to never check for "null" and let the JVM do that, This behaviour
>>>> is _not_ consistent throughout CM.]
>>>>
>>>> Number of occurrences of CM exceptions that are subclasses of those Java
>>>> standard exceptions:
>>>>  * IllegalStateException (43)
>>>>  * UnsupportedOperationException (22)
>>>>  * ArithmeticException (54)
>>>>
>>>> In summary, I have no problem with a "MathRuntimeException" base class which
>>>> "MathIllegalArgumentException", "MathIllegalStateException",
>>>> "MathUnsupportedOperationException", "MathArithmeticException" would inherit
>>>> from.
>>>>
>>>> Applications that call CM would be safe (apart from bugs raising "NPE")
>>>> with a unique catch clause intercepting "MathRuntimeException".
>>> I am happy (and surprised) to read that.
>>> I would really much like to go back to a single root exception
>>> hierarchy. This both helps top level application as depending on context
>>> they can either pinpoint the exception they want to catch or they can
>>> have a grab all strategy. It is their choice.
>> I like throwing (and catching) standard exceptions instead of
>> inventing variants of them, which is why I favored having MathIAE
>> inherit from IAE, etc.  I would have preferred to just throw IAE
>> directly, but we could not agree on how to do that and preserve
>> localization, so we ended up with the current setup where we have
>> custom variants, but they inherit from the standard exceptions.  I
>> am curious, Luc, about exactly what kinds of use cases will really
>> be easier / better for users if we go back to a single-rooted
>> hierarchy.  I get that instead of "catch Exception" or "catch
>> RuntimeException" you can at the top level "catch MathRTE" and that
>> will catch only the exceptions that come (at least originally) from
>> the [math] code.
> Yes, but this is only one aspect.
>
>> Can you help me understand via an example how that
>> is a big benefit that is worth more than being able to "catch IAE"
>> or "catch IOE" directly?
> One of the problems I encounter occurs when building large applications
> with several components layers. At an intermediate level, say just above
> [math], developers know what they are calling and they may decide to
> catch an exception they know about, if they are able to identify it is
> thrown (which is not always obvious). They may also decide the exception
> cannot be handled at their level and simply let it propagate upward. As
> you go upward in the software layers, with different development teams,
> you lose this knowledge and people don't even understand anything about
> mathematics. They can however still catch some large scope exceptions,
> one type per component (say a MathRuntimeException, and a MylibException
> if they know these two sub-components are used). They won't do anything
> with the exception but nicely display them in the graphical user
> interface and stop the application. This works well as long as there is
> one single root per library, but it does not scale with 40 different
> exceptions per libraries.

I think I get your point, but again given transitive / nested
dependencies I would not want to depend on it, even if all of the
components have single-rooted exception hierarchies.  This is
especially true if not all components adhere to the "wrap
everything" rule - i.e., if they can generate and/or propagate RTEs
that do not inherit from their base exception class.  From the
standpoint of the caller, for example, what is the difference
between [math]

0)  throwing IAE
1)  throwing MathIAE derived from IAE
2)  throwing MathIAE derived from MathRTE (base)
assuming that [math] is not signing up to wrap and rethrow every
exception - including IAE - we get from JDK classes?  Will the
caller actually do anything different if the RTE is math-wrapped vs
"naked" but coming out of the [math] code?  I understand that the
try/catch may be several layers removed from the code calling a
[math] API. 

Same applies to NPE, which we don't subclass now, but mostly handle
as IAE.

I guess one thing we might consider is trying to design for the
invariant that we never propagate RTEs without wrapping.  But that
would be a lot of work to retrofit and would have a performance cost.

> Another problem is maintenance. Even if you consider the intermediate
> developer did his work really accurately and managed to identify all
> exceptions thrown by the methods he calls in one version of Apache
> Commons Math. When we change an error detection and decide that a method
> that did throw only MaxCountExceededException a method should throw
> NumberIsToolLargeException instead (or in addition to the existing one),
> then the calling code would still compile, but the new exception would
> now go all the way upward. The two exceptions have no common ancestor
> that can be catched, except Exception itself. With a single rooted
> hierarchy, users can use some defensive programming: they can catch the
> common root and be safe when we change some internal details.
>
> A single root would also bring two things I find useful.
>
> The first useful thing is that the ExceptionContextProvider could be
> implemented at the root level, so we could retrieve this context (in
> fact, I sometime needs even to retrive the pattern and the arguments
> from the context, and we also miss getters for that, but they are easy
> to add). It is not possible to catch ExceptionContextProvider because it
> is not a throwable (Throwable is a class, not an interface, so we
> inherit the Throwable nature from the top level class, not as
> implementing the ExceptionContextProvider interface.
>
> The second useful thing is for [math] development itself. With a single
> root, we can temporarily change its parent class from RuntimeException
> to Exception, then fix all missing throws declaration and javadoc, then
> put the parent class back before committing. This would help having more
> up to date declarations. For now, I am sure we have missed a lot of our
> own exceptions and let them propagate upward without anybody knowing it.
> As a test, I have just changed the parent for
> MathIllegalArgumentException to Exception. I got 1384 compilation
> errors. Just going to the first one (a constructor of
> BaseAbstractUnivariateIntegrator), I saw we did not advertise the fact
> it may throw NumberIsTooSmallException and NotStrictlyPositiveException,
> neither in a throws declaration nor in the javadoc. I did not look at
> the 1383 other errors...

This is a good point.
>
>> What I am missing is how knowing that an
>> aspecific RTE came from within [math] makes a difference.  I am
>> skeptical about ever depending on that kind of conclusion because
>> dependencies may bring [math] code in at multiple levels.  Also, is
>> there an implied assumption in your ideal setup that *no* exceptions
>> propagate to [math] clients other than MRTE (i.e. we catch and wrap
>> everything)?
> No, I don't make this assumption. I consider that at upper levels, code
> can receive exception from all layers underneath ([math] at the very
> bottom, but also other layers in between). With two or three layers, you
> can still handle a few library-wide exceptions (see my example with
> MathRuntimeException, and MylibException above). However, if at one
> level the development rules state that all exception must be caught and
> wrapped (this happens in some critical systems contexts), then a single
> root hierarchy helps a lot.

But if we allow some exceptions to propagate unwrapped, this does
not work, unless I am missing the point here.
>
> My point is that with a single root, we can get the best of two worlds:
> large scope catches and pinpointed catches. The choice remains open for
> users. With a multi-rooted hierarchy, we force users to duplicate the
> same work for all exceptions we may throw, and we also force them to
> recheck everything when we publish a new version, even despite we
> ourselves fail to document these exceptions accurately.

We need to fix the documentation.  If going back to a single root
makes automatic detection of gaps possible, that by itself is almost
enough to get me to agree to go back to the single root.  Your
arguments above (which I honestly only partially follow) are enough
to make me +0 for this change.  I think I probably put too much
weight on favoring standard exceptions when we are really only
talking about "reinventing" a handful of them.

Phil
>
> best regards,
> Luc
>
>> Phil
>>> For sure, this is something that can be done only for a major release.
>>>
>>>>>> Client apps cannot do more with checked exceptions, and can be made as
>>>>>> "safe" by wrapping calls in try-blocks.
>>>>>> On the other hand, client source code is much cleaner without unnecessary
>>>>>> "throws" clauses or wrapping of checked expections at all levels.
>>>>>> Some Java experts go as far as saying that checked exceptions were a
>>>>>> language design mistake (never repeated in languages invented more
>>>>>> recently).
>>>>>>
>>>>>>> There is a reason that NaNs exist.  It is much cheaper to return a
>>>>>>> NaN than to raise (and force the client to handle) an exception. 
>>>>>>> This is not precise and probably can't be made so, but I have always
>>>>>>> looked at things more or less like this:
>>>>>>>
>>>>>>> 0) IAE (which I see no need to specialize as elaborately as we have
>>>>>>> done in [math]) is for clear violation of the documented API
>>>>>>> contract.  The actual parameters "don't make sense" in the context
>>>>>>> of the API.
>>>>>> The "elaboration" is actually very basic (but that's a matter of taste), but
>>>>>> it was primarily promoted (by me) in order to hide (as much as possible) the
>>>>>> ugliness (another matter of taste) of the "LocalizedFormats" enum, and its
>>>>>> inconsequent use (duplication). [Cf. discussions in the archive.]
>>>>>>
>>>>>>> 1) NaN can be returned as the result of a computation which, when
>>>>>>> started with legitimate arguments, does not result in a
>>>>>>> representable value.
>>>>>> According to this description, Sébastien's case _must_ be handled by an
>>>>>> exception: the argument is _not_ legtimate.
>>>>>> The usage of NaN I was referring to is to let a computation proceed ("follow
>>>>>> an unexceptional path") in the hope that the final result might still be
>>>>>> meaningful.
>>>>>> If the NaN persists, not checking for it and signalling the problem (i.e.
>>>>>> raise an exception) is a bug. This is to avoid that (and be robust) that we
>>>>>> do extensive precondition checks in CM. But this has the unavoidable
>>>>>> drawback that the use of NaN as suggested is much less likely to be feasible
>>>>>> when calling CM code. Once realizing that, it becomes much less obvious that
>>>>>> there is _any_ advantage of letting NaNs propagate...
>>>>>> [Anyone has an example of NaN usage? Please let me know.]
>>>>> I use NaN a lot as an indicator that a variable has not been fully
>>>>> initialized yet. This occurs for example in iterative algorithms, where
>>>>> some result is computed deep inside some loop and we don't know when the
>>>>> loop will end. Then I write something along these lines:
>>>>>
>>>>>   while (Double.isNaN(result)) {
>>>>>      // do something that hopefully will change result to non-NaN
>>>>>   }
>>>>>
>>>>>   // now I know result has been computed
>>>>>
>>>>> Another use is to initialize some fields in class to values I know are
>>>>> not meaningful. I can then us NaN as a marker to do lazy evaluation for
>>>>> values that takes time to compute and should be computed only when both
>>>>> really needed and when everything required for their computation is
>>>>> available.
>>>> I should have said "[...] example of NaN usage, beyond singling out
>>>> unitialized data [...]". The above makes use of NaN as "invalid" because it
>>>> is not initialized (yet).
>>> Yes.
>>>
>>>> I'd assume that if "result" stays NaN after the allowed number of
>>>> iterations, you raise an exception, i.e. you don't propagate NaN as the
>>>> output of a computation that cannot provide a useful result. However, this
>>>> (propagating NaN) is the behaviour of "srqt(-1)", for example.
>>>> Thus, if you raise an exception, your computation does not behave in the
>>>> same way as the function "sqrt".
>>>>
>>>>> Another use is simply to detect some special cases in computations (like
>>>>> sqrt(-1) or 0/0). I do the computation first and check the NaN
>>>>> afterwards. See for example the detection of NaNs in the linear
>>>>> combinations in MathArrays or in the nth order Brent solver.
>>>> OK, this is a good example, in line with the intended usage of NaN (as it
>>>> avoids inserting control structures in the computation).
>>> Yes. One of the main use case for this is when a computation involves a
>>> loop and failure is very rare. So we avoid costly numerous if statements
>>> within the loop and do a single check. In the few cases this single
>>> check fails, we go to a diffrent branch to handle the failure. This is
>>> exactly what is done in linear combination.
>>>
>>>>> Another use of NaNs occurs when integrating various code components from
>>>>> different origins in a single application. Data is forwarded between the
>>>>> various components in all directions. Components never share the same
>>>>> exceptions mechanisms. Components either process NaNs specially (which
>>>>> is good) or they let the processor propagate them (it is what the IEEE
>>>>> standard mandates) and at the end you can detect it reliably at
>>>>> application level.
>>>> I'm not sure I understand this. Is it good or bad that a component lets NaNs
>>>> propagate? Are there situations when it's good and others where it's bad?
>>> In the cases I encountered, it is always good to have NaNs propagated. A
>>> component that is not an application by itself but only a part (low or
>>> intermediate level) often cannot decide at its level how to handle NaNs
>>> except in rare cases. So it propagates them upward. The previous example
>>> (linear combination in [math]) is of course a counter-example: we are at
>>> low level, we know how to handle the NaN for this operation, so we
>>> detect it and fix it.
>>>
>>>> That's why I was asking (cf. quote from previous post below) what are the
>>>> criteria, so that contributors know how to write code when the feature falls
>>>> in one or the other category.
>>>>
>>>>>>> The problem is that contracts can often be written so that instances
>>>>>>> of 1) are turned into instances of 0).  Gamma(-) is a great
>>>>>>> example.  The singularities at negative integers could be viewed as
>>>>>>> making negative integer arguments "illegal" or "nonsense" from the
>>>>>>> API standpoint,
>>>>>> They are just nonsense (not just from an API standpoint).
>>>>>>
>>>>>>> or legitimate arguments for which no well-defined,
>>>>>>> representable value can be returned.  Personally, I would prefer to
>>>>>>> get NaN back from this function and just point out the existence of
>>>>>>> the singularities in the javadoc.
>>>>>> This is consistent with how basic math functions behave, but not with the
>>>>>> general rule/convention of most of CM code.
>>>>>> It may be fine that we have several ways to deal with exceptional
>>>>>> conditions, but it might be nice, as with formatting, to have rules so that
>>>>>> we know how to write contributions.
>>>>> Too many rules are not a solution, especially when there are no tools to
>>>>> help enforce these rules are obeyed. Relying only on the fact human
>>>>> proof-reading will enforce them is wishful thinking.
>>>>>
>>>> What is "too many"? ["How long should a person's legs be?" ;-)]
>>>> I don't agree with the "wishful thinking" statement; a "diff" could probably
>>>> show a lot a manual corrections to the code and comment formatting. [Mainly
>>>> in the sources which I touched at some point...]
>>> I'm not sure I understand your point. Mine is that rules that are not
>>> backed by automated tools are a pain to enforce, and hence are not
>>> fulfilled most of the time, except at a tremendous human resource cost.
>>> In fact, even rules which can be associated with tools are broken during
>>> development for some time. We do not use
>>> checkstyle/CLIRR/findbugs/PMD/RAT for all commits for example, but do a
>>> fix pass from time to time.
>>>
>>>> There are other areas where there is only human control, namely the "svn
>>>> log" messages where (no less picky) rules are enforced just because it
>>>> helps _humans_ in their change overview task.
>>>>
>>>> As pointed out by Jared, it's not a big problem to comply with rules once
>>>> you know them.
>>> I fully agree with that, but I also think Phil is right when he says too
>>> many rules may discourage potential contributors. I remember a link he
>>> sent to us months ago about to a presentation by Michael Meeks about
>>> interacting with new developers
>>> <http://people.gnome.org/~michael/data/2011-10-13-new-developers.pdf>.
>>> Slides numers 3 an 4 are a fabulous example. I think we are lucky Jared
>>> has this state of mind and accepts picky rules easily. I'm not sure such
>>> an open mind is widespread among potential contributors.
>>>
>>>> Keeping source code tidy is quite helpful, and potential contributors will
>>>> be happy that they can read any CM source files and immediately recognize
>>>> that they are part of the same library...
>>> Yes, of course. But the entry barrier should not be too high.
>>>
>>> best regards,
>>> Luc
>>>
>>>> Best 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
>>>
>>>
>> ---------------------------------------------------------------------
>> 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
>
>



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

Re: [math] Re: Single root for Exceptions

[Gilles Sadowski <gi...@harfang.homelinux.org>]

Hello.

> >
> >> >>>
> >> >>> in ConjugateGradient, I get the following error
> >> >>>
> >> >>> "Exception NonPositiveDefiniteOperatorException is not compatible with
> >> >>> throws clause in
> >> >>> PreconditionedIterativeLinearSolver.solveInPlace(RealLinearOperator,
> >> >>> RealLinearOperator, RealVector, RealVector)"
> >> >>>
> >> >>> This comes from the fact that general iterative solvers do not require
> >> >>> positive definite operators (therefore, no
> >> >>> "throws NonPositiveDefiniteOperatorException" clause in the signature of
> >> >>> PreconditionedIterativeLinearSolver.solveInPlace), while conjugate
> >> >>> gradient does.
> >> >>>
> >> >>> Do I need to add the "throws NonPositiveDefiniteOperatorException"
> >> >>> clause in the signature of
> >> >>> PreconditionedIterativeLinearSolver.solveInPlace as well?
> >> >>
> >> >> I think so, as users may use a ConjugateGradient and store it in a
> >> >> variable declared with the base class only. However, I don't know if
> >> >> adding an unchecked exception to the signature of an interface is a
> >> >> compatible change or not.
> >> >>
> >> >> Luc
> >> >>
> >> > clirr does not seem to be complaining, so I'll do as you say. Here is
> >> > what I'm planning to add to the javadoc of the mother abstract class.
> >> > What do you think?
> >> >
> >> >      * @throws NonPositiveDefiniteOperatorException if {@code a} or {@code m}
> >> >      * is not positive definite (required by some iterative solvers)
> >>
> >> Perfect!
> >
> > I don't agree on the principle that base classes/interfaces should be aware
> > of the detailed requirements of their implementations.
> > We can foresee that subclasses might need to throw _some_ kind of exception
> > when something (yet unknown at the time of the interface design) goes wrong.
> > But base classes (or interfaces) should not have to change when a new class
> > extends (or implements) it.
> >
> > For cases like the above, we must create a parent exception (or use an
> > existing one if it is appropriate) in order to convey that subclasses
> > _might_ throw exceptions that inherit from that one.
> > It this particular case, it seems that operators that are not positive
> > definite are illegal for method "solveInPlace", hence we conclude (not
> > surprisingly) that "MathIllegalArgumentException" can be thrown from classes
> > that implement "RealLinearOperator.solveInPlace".
> >
> > In fact, this is even too much of a "guessing" work. And this where a single
> > root can be used to clearly advertize that, by design, CM is supposed to
> > throw only (subclasses of) "MathRunimeException". _That_ exception, and
> > _nothing_ else should really be inserted in the "throws" clause of upper
> > level base classes and interfaces.
> >
> > Referring to the above example, it is the duty of the user of CM to read the
> > documentation of the (concrete) classes he uses if he wants to know which
> > subclass of "MathRuntimeException" may actually be thrown; it is not enough
> > to read the documentation of the interface!
> > To be clear, CM will become a total clutter if upper levels attempt to
> > report everything all the way down. This is in blatant contradiction with
> > the principle (or rule, or best practice) of encapsulation.
> >
> >
> > Best regards,
> > Gilles
> >
> >> > [...]
> >
> > P.S. Practically, at this point, I propose to not touch interfaces or base
> >      classes, but only add the "throws" clauses where the methods actually
> >      throw the exceptions, and in some cases, one level up (where it is
> >      still obvious that a particular condition is required).
> >      Of course, that makes it impossible to test the "switch to checked
> >      exception" as the work is in progress. For this, let's wait until all
> >      the first pass has been completed, then we can see what is missing,
> >      and decide while seeing the picture.
> >
> I think some exceptions *must* be shown in some interfaces. For
> example, DimensionMismatchException in FieldMatrix.mul(FieldMatrix).

I didn't deny it. I suggested that _for the time being_, we add the obvious
clauses, i.e. those where the "throw" statement is visible in the body of
the function, or where we know that a method called by this method can
throw[1].
Then we can "propagate" the changes upwards, where it makes sense.

I agree that in your example, the exception should be advertized in the
interface, because this is a precondition of the operation that must hold
for _any_ implementation. [Thus you can add it now if you want ;-)].



Best regards,
Gilles

[1] E.g. like the various "verify..." utility methods.

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

Re: [math] Re: Single root for Exceptions

[Sébastien Brisard <se...@m4x.org>]

Hi again,

2012/9/1 Gilles Sadowski <gi...@harfang.homelinux.org>:
> Hello.
>
>> >>>
>> >>> in ConjugateGradient, I get the following error
>> >>>
>> >>> "Exception NonPositiveDefiniteOperatorException is not compatible with
>> >>> throws clause in
>> >>> PreconditionedIterativeLinearSolver.solveInPlace(RealLinearOperator,
>> >>> RealLinearOperator, RealVector, RealVector)"
>> >>>
>> >>> This comes from the fact that general iterative solvers do not require
>> >>> positive definite operators (therefore, no
>> >>> "throws NonPositiveDefiniteOperatorException" clause in the signature of
>> >>> PreconditionedIterativeLinearSolver.solveInPlace), while conjugate
>> >>> gradient does.
>> >>>
>> >>> Do I need to add the "throws NonPositiveDefiniteOperatorException"
>> >>> clause in the signature of
>> >>> PreconditionedIterativeLinearSolver.solveInPlace as well?
>> >>
>> >> I think so, as users may use a ConjugateGradient and store it in a
>> >> variable declared with the base class only. However, I don't know if
>> >> adding an unchecked exception to the signature of an interface is a
>> >> compatible change or not.
>> >>
>> >> Luc
>> >>
>> > clirr does not seem to be complaining, so I'll do as you say. Here is
>> > what I'm planning to add to the javadoc of the mother abstract class.
>> > What do you think?
>> >
>> >      * @throws NonPositiveDefiniteOperatorException if {@code a} or {@code m}
>> >      * is not positive definite (required by some iterative solvers)
>>
>> Perfect!
>
> I don't agree on the principle that base classes/interfaces should be aware
> of the detailed requirements of their implementations.
> We can foresee that subclasses might need to throw _some_ kind of exception
> when something (yet unknown at the time of the interface design) goes wrong.
> But base classes (or interfaces) should not have to change when a new class
> extends (or implements) it.
>
> For cases like the above, we must create a parent exception (or use an
> existing one if it is appropriate) in order to convey that subclasses
> _might_ throw exceptions that inherit from that one.
> It this particular case, it seems that operators that are not positive
> definite are illegal for method "solveInPlace", hence we conclude (not
> surprisingly) that "MathIllegalArgumentException" can be thrown from classes
> that implement "RealLinearOperator.solveInPlace".
>
> In fact, this is even too much of a "guessing" work. And this where a single
> root can be used to clearly advertize that, by design, CM is supposed to
> throw only (subclasses of) "MathRunimeException". _That_ exception, and
> _nothing_ else should really be inserted in the "throws" clause of upper
> level base classes and interfaces.
>
> Referring to the above example, it is the duty of the user of CM to read the
> documentation of the (concrete) classes he uses if he wants to know which
> subclass of "MathRuntimeException" may actually be thrown; it is not enough
> to read the documentation of the interface!
> To be clear, CM will become a total clutter if upper levels attempt to
> report everything all the way down. This is in blatant contradiction with
> the principle (or rule, or best practice) of encapsulation.
>
>
> Best regards,
> Gilles
>
>> > [...]
>
> P.S. Practically, at this point, I propose to not touch interfaces or base
>      classes, but only add the "throws" clauses where the methods actually
>      throw the exceptions, and in some cases, one level up (where it is
>      still obvious that a particular condition is required).
>      Of course, that makes it impossible to test the "switch to checked
>      exception" as the work is in progress. For this, let's wait until all
>      the first pass has been completed, then we can see what is missing,
>      and decide while seeing the picture.
>
I think some exceptions *must* be shown in some interfaces. For
example, DimensionMismatchException in FieldMatrix.mul(FieldMatrix).

Sébastien


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

Re: [math] Re: Single root for Exceptions

[Phil Steitz <ph...@gmail.com>]

On 9/2/12 7:35 PM, Sébastien Brisard wrote:
> Hi,
> here is another problem. In
> MatrixUtils.createFieldIdentityMatrix(Field<T>, int), the constructor
> Array2DRowFieldMatrix(Field<T>, T[][], boolean) is called. This
> constructor throws a DimensionMismatchException if the data array is
> not rectangular. This is never going to occur in
> createFieldIdentityMatrix, so what should we do
> 1. Populate the throws clause of createFieldIdentityMatrix with
> DimensionMismatchException anyway?
> 2. try/catch with empty catch, which I find ugly?

Neither.  The exception will (provably) never be thrown.  Therefore
there is no reason to advertise it.
Just allow it as an exception when applying "rhymes with truc's" trick.

What we need to accomplish is to effectively advertise all
exceptions that a caller may actually see.  In some cases,
superclasses of the exceptions being propagated may be appropriate
and in extreme cases, due to holes in the hierarchy or deep nesting
of the API, the only thing that will make sense to the caller is
MRTE.  This should be a last resort.

Phil
>
> Sébastien
>
> 2012/9/3 Sébastien Brisard <se...@m4x.org>:
>> Hi,
>>
>> 2012/9/1 Gilles Sadowski <gi...@harfang.homelinux.org>:
>>> Hello.
>>>
>>>>>>> in ConjugateGradient, I get the following error
>>>>>>>
>>>>>>> "Exception NonPositiveDefiniteOperatorException is not compatible with
>>>>>>> throws clause in
>>>>>>> PreconditionedIterativeLinearSolver.solveInPlace(RealLinearOperator,
>>>>>>> RealLinearOperator, RealVector, RealVector)"
>>>>>>>
>>>>>>> This comes from the fact that general iterative solvers do not require
>>>>>>> positive definite operators (therefore, no
>>>>>>> "throws NonPositiveDefiniteOperatorException" clause in the signature of
>>>>>>> PreconditionedIterativeLinearSolver.solveInPlace), while conjugate
>>>>>>> gradient does.
>>>>>>>
>>>>>>> Do I need to add the "throws NonPositiveDefiniteOperatorException"
>>>>>>> clause in the signature of
>>>>>>> PreconditionedIterativeLinearSolver.solveInPlace as well?
>>>>>> I think so, as users may use a ConjugateGradient and store it in a
>>>>>> variable declared with the base class only. However, I don't know if
>>>>>> adding an unchecked exception to the signature of an interface is a
>>>>>> compatible change or not.
>>>>>>
>>>>>> Luc
>>>>>>
>>>>> clirr does not seem to be complaining, so I'll do as you say. Here is
>>>>> what I'm planning to add to the javadoc of the mother abstract class.
>>>>> What do you think?
>>>>>
>>>>>      * @throws NonPositiveDefiniteOperatorException if {@code a} or {@code m}
>>>>>      * is not positive definite (required by some iterative solvers)
>>>> Perfect!
>>> I don't agree on the principle that base classes/interfaces should be aware
>>> of the detailed requirements of their implementations.
>>> We can foresee that subclasses might need to throw _some_ kind of exception
>>> when something (yet unknown at the time of the interface design) goes wrong.
>>> But base classes (or interfaces) should not have to change when a new class
>>> extends (or implements) it.
>>>
>>> For cases like the above, we must create a parent exception (or use an
>>> existing one if it is appropriate) in order to convey that subclasses
>>> _might_ throw exceptions that inherit from that one.
>>> It this particular case, it seems that operators that are not positive
>>> definite are illegal for method "solveInPlace", hence we conclude (not
>>> surprisingly) that "MathIllegalArgumentException" can be thrown from classes
>>> that implement "RealLinearOperator.solveInPlace".
>>>
>>> In fact, this is even too much of a "guessing" work. And this where a single
>>> root can be used to clearly advertize that, by design, CM is supposed to
>>> throw only (subclasses of) "MathRunimeException". _That_ exception, and
>>> _nothing_ else should really be inserted in the "throws" clause of upper
>>> level base classes and interfaces.
>>>
>>> Referring to the above example, it is the duty of the user of CM to read the
>>> documentation of the (concrete) classes he uses if he wants to know which
>>> subclass of "MathRuntimeException" may actually be thrown; it is not enough
>>> to read the documentation of the interface!
>>> To be clear, CM will become a total clutter if upper levels attempt to
>>> report everything all the way down. This is in blatant contradiction with
>>> the principle (or rule, or best practice) of encapsulation.
>>>
>> OK, but the code is going to become a total clutter anyway. Indeed, in
>> PreconditionedIterativeLinearSolver, there are a bunch of solve()
>> method, all based on the abstract method
>>     public abstract RealVector solveInPlace(RealLinearOperator a,
>>                                             RealLinearOperator m,
>>                                             RealVector b,
>>                                             RealVector x0)
>>
>> In conjugate gradient, the above method throws a
>> NonPositiveDefiniteOperatorException. This means that in the
>> implementation of ConjugateGradient, I need to override every single
>> solve method that are implemented in the base class, just to add the
>> proper throws clause. At this point, I have stopped "populating the
>> throws clause", as I am not sure it's the best way to go.
>> S
>>> Best regards,
>>> Gilles
>>>
>>>>> [...]
>>> P.S. Practically, at this point, I propose to not touch interfaces or base
>>>      classes, but only add the "throws" clauses where the methods actually
>>>      throw the exceptions, and in some cases, one level up (where it is
>>>      still obvious that a particular condition is required).
>>>      Of course, that makes it impossible to test the "switch to checked
>>>      exception" as the work is in progress. For this, let's wait until all
>>>      the first pass has been completed, then we can see what is missing,
>>>      and decide while seeing the picture.
>>>
>>> ---------------------------------------------------------------------
>>> 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
>
>


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

Re: [math] Re: Single root for Exceptions

[Sébastien Brisard <se...@m4x.org>]

Hi,
here is another problem. In
MatrixUtils.createFieldIdentityMatrix(Field<T>, int), the constructor
Array2DRowFieldMatrix(Field<T>, T[][], boolean) is called. This
constructor throws a DimensionMismatchException if the data array is
not rectangular. This is never going to occur in
createFieldIdentityMatrix, so what should we do
1. Populate the throws clause of createFieldIdentityMatrix with
DimensionMismatchException anyway?
2. try/catch with empty catch, which I find ugly?

Sébastien

2012/9/3 Sébastien Brisard <se...@m4x.org>:
> Hi,
>
> 2012/9/1 Gilles Sadowski <gi...@harfang.homelinux.org>:
>> Hello.
>>
>>> >>>
>>> >>> in ConjugateGradient, I get the following error
>>> >>>
>>> >>> "Exception NonPositiveDefiniteOperatorException is not compatible with
>>> >>> throws clause in
>>> >>> PreconditionedIterativeLinearSolver.solveInPlace(RealLinearOperator,
>>> >>> RealLinearOperator, RealVector, RealVector)"
>>> >>>
>>> >>> This comes from the fact that general iterative solvers do not require
>>> >>> positive definite operators (therefore, no
>>> >>> "throws NonPositiveDefiniteOperatorException" clause in the signature of
>>> >>> PreconditionedIterativeLinearSolver.solveInPlace), while conjugate
>>> >>> gradient does.
>>> >>>
>>> >>> Do I need to add the "throws NonPositiveDefiniteOperatorException"
>>> >>> clause in the signature of
>>> >>> PreconditionedIterativeLinearSolver.solveInPlace as well?
>>> >>
>>> >> I think so, as users may use a ConjugateGradient and store it in a
>>> >> variable declared with the base class only. However, I don't know if
>>> >> adding an unchecked exception to the signature of an interface is a
>>> >> compatible change or not.
>>> >>
>>> >> Luc
>>> >>
>>> > clirr does not seem to be complaining, so I'll do as you say. Here is
>>> > what I'm planning to add to the javadoc of the mother abstract class.
>>> > What do you think?
>>> >
>>> >      * @throws NonPositiveDefiniteOperatorException if {@code a} or {@code m}
>>> >      * is not positive definite (required by some iterative solvers)
>>>
>>> Perfect!
>>
>> I don't agree on the principle that base classes/interfaces should be aware
>> of the detailed requirements of their implementations.
>> We can foresee that subclasses might need to throw _some_ kind of exception
>> when something (yet unknown at the time of the interface design) goes wrong.
>> But base classes (or interfaces) should not have to change when a new class
>> extends (or implements) it.
>>
>> For cases like the above, we must create a parent exception (or use an
>> existing one if it is appropriate) in order to convey that subclasses
>> _might_ throw exceptions that inherit from that one.
>> It this particular case, it seems that operators that are not positive
>> definite are illegal for method "solveInPlace", hence we conclude (not
>> surprisingly) that "MathIllegalArgumentException" can be thrown from classes
>> that implement "RealLinearOperator.solveInPlace".
>>
>> In fact, this is even too much of a "guessing" work. And this where a single
>> root can be used to clearly advertize that, by design, CM is supposed to
>> throw only (subclasses of) "MathRunimeException". _That_ exception, and
>> _nothing_ else should really be inserted in the "throws" clause of upper
>> level base classes and interfaces.
>>
>> Referring to the above example, it is the duty of the user of CM to read the
>> documentation of the (concrete) classes he uses if he wants to know which
>> subclass of "MathRuntimeException" may actually be thrown; it is not enough
>> to read the documentation of the interface!
>> To be clear, CM will become a total clutter if upper levels attempt to
>> report everything all the way down. This is in blatant contradiction with
>> the principle (or rule, or best practice) of encapsulation.
>>
> OK, but the code is going to become a total clutter anyway. Indeed, in
> PreconditionedIterativeLinearSolver, there are a bunch of solve()
> method, all based on the abstract method
>     public abstract RealVector solveInPlace(RealLinearOperator a,
>                                             RealLinearOperator m,
>                                             RealVector b,
>                                             RealVector x0)
>
> In conjugate gradient, the above method throws a
> NonPositiveDefiniteOperatorException. This means that in the
> implementation of ConjugateGradient, I need to override every single
> solve method that are implemented in the base class, just to add the
> proper throws clause. At this point, I have stopped "populating the
> throws clause", as I am not sure it's the best way to go.
> S
>>
>> Best regards,
>> Gilles
>>
>>> > [...]
>>
>> P.S. Practically, at this point, I propose to not touch interfaces or base
>>      classes, but only add the "throws" clauses where the methods actually
>>      throw the exceptions, and in some cases, one level up (where it is
>>      still obvious that a particular condition is required).
>>      Of course, that makes it impossible to test the "switch to checked
>>      exception" as the work is in progress. For this, let's wait until all
>>      the first pass has been completed, then we can see what is missing,
>>      and decide while seeing the picture.
>>
>> ---------------------------------------------------------------------
>> 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

Re: [math] Re: Single root for Exceptions

[Sébastien Brisard <se...@m4x.org>]

Hi,

2012/9/1 Gilles Sadowski <gi...@harfang.homelinux.org>:
> Hello.
>
>> >>>
>> >>> in ConjugateGradient, I get the following error
>> >>>
>> >>> "Exception NonPositiveDefiniteOperatorException is not compatible with
>> >>> throws clause in
>> >>> PreconditionedIterativeLinearSolver.solveInPlace(RealLinearOperator,
>> >>> RealLinearOperator, RealVector, RealVector)"
>> >>>
>> >>> This comes from the fact that general iterative solvers do not require
>> >>> positive definite operators (therefore, no
>> >>> "throws NonPositiveDefiniteOperatorException" clause in the signature of
>> >>> PreconditionedIterativeLinearSolver.solveInPlace), while conjugate
>> >>> gradient does.
>> >>>
>> >>> Do I need to add the "throws NonPositiveDefiniteOperatorException"
>> >>> clause in the signature of
>> >>> PreconditionedIterativeLinearSolver.solveInPlace as well?
>> >>
>> >> I think so, as users may use a ConjugateGradient and store it in a
>> >> variable declared with the base class only. However, I don't know if
>> >> adding an unchecked exception to the signature of an interface is a
>> >> compatible change or not.
>> >>
>> >> Luc
>> >>
>> > clirr does not seem to be complaining, so I'll do as you say. Here is
>> > what I'm planning to add to the javadoc of the mother abstract class.
>> > What do you think?
>> >
>> >      * @throws NonPositiveDefiniteOperatorException if {@code a} or {@code m}
>> >      * is not positive definite (required by some iterative solvers)
>>
>> Perfect!
>
> I don't agree on the principle that base classes/interfaces should be aware
> of the detailed requirements of their implementations.
> We can foresee that subclasses might need to throw _some_ kind of exception
> when something (yet unknown at the time of the interface design) goes wrong.
> But base classes (or interfaces) should not have to change when a new class
> extends (or implements) it.
>
> For cases like the above, we must create a parent exception (or use an
> existing one if it is appropriate) in order to convey that subclasses
> _might_ throw exceptions that inherit from that one.
> It this particular case, it seems that operators that are not positive
> definite are illegal for method "solveInPlace", hence we conclude (not
> surprisingly) that "MathIllegalArgumentException" can be thrown from classes
> that implement "RealLinearOperator.solveInPlace".
>
> In fact, this is even too much of a "guessing" work. And this where a single
> root can be used to clearly advertize that, by design, CM is supposed to
> throw only (subclasses of) "MathRunimeException". _That_ exception, and
> _nothing_ else should really be inserted in the "throws" clause of upper
> level base classes and interfaces.
>
> Referring to the above example, it is the duty of the user of CM to read the
> documentation of the (concrete) classes he uses if he wants to know which
> subclass of "MathRuntimeException" may actually be thrown; it is not enough
> to read the documentation of the interface!
> To be clear, CM will become a total clutter if upper levels attempt to
> report everything all the way down. This is in blatant contradiction with
> the principle (or rule, or best practice) of encapsulation.
>
OK, but the code is going to become a total clutter anyway. Indeed, in
PreconditionedIterativeLinearSolver, there are a bunch of solve()
method, all based on the abstract method
    public abstract RealVector solveInPlace(RealLinearOperator a,
                                            RealLinearOperator m,
                                            RealVector b,
                                            RealVector x0)

In conjugate gradient, the above method throws a
NonPositiveDefiniteOperatorException. This means that in the
implementation of ConjugateGradient, I need to override every single
solve method that are implemented in the base class, just to add the
proper throws clause. At this point, I have stopped "populating the
throws clause", as I am not sure it's the best way to go.
S
>
> Best regards,
> Gilles
>
>> > [...]
>
> P.S. Practically, at this point, I propose to not touch interfaces or base
>      classes, but only add the "throws" clauses where the methods actually
>      throw the exceptions, and in some cases, one level up (where it is
>      still obvious that a particular condition is required).
>      Of course, that makes it impossible to test the "switch to checked
>      exception" as the work is in progress. For this, let's wait until all
>      the first pass has been completed, then we can see what is missing,
>      and decide while seeing the picture.
>
> ---------------------------------------------------------------------
> 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

Re: [math] Re: Single root for Exceptions

[Gilles Sadowski <gi...@harfang.homelinux.org>]

Hello.

> >>>
> >>> in ConjugateGradient, I get the following error
> >>>
> >>> "Exception NonPositiveDefiniteOperatorException is not compatible with
> >>> throws clause in
> >>> PreconditionedIterativeLinearSolver.solveInPlace(RealLinearOperator,
> >>> RealLinearOperator, RealVector, RealVector)"
> >>>
> >>> This comes from the fact that general iterative solvers do not require
> >>> positive definite operators (therefore, no
> >>> "throws NonPositiveDefiniteOperatorException" clause in the signature of
> >>> PreconditionedIterativeLinearSolver.solveInPlace), while conjugate
> >>> gradient does.
> >>>
> >>> Do I need to add the "throws NonPositiveDefiniteOperatorException"
> >>> clause in the signature of
> >>> PreconditionedIterativeLinearSolver.solveInPlace as well?
> >>
> >> I think so, as users may use a ConjugateGradient and store it in a
> >> variable declared with the base class only. However, I don't know if
> >> adding an unchecked exception to the signature of an interface is a
> >> compatible change or not.
> >>
> >> Luc
> >>
> > clirr does not seem to be complaining, so I'll do as you say. Here is
> > what I'm planning to add to the javadoc of the mother abstract class.
> > What do you think?
> > 
> >      * @throws NonPositiveDefiniteOperatorException if {@code a} or {@code m}
> >      * is not positive definite (required by some iterative solvers)
> 
> Perfect!

I don't agree on the principle that base classes/interfaces should be aware
of the detailed requirements of their implementations.
We can foresee that subclasses might need to throw _some_ kind of exception
when something (yet unknown at the time of the interface design) goes wrong.
But base classes (or interfaces) should not have to change when a new class
extends (or implements) it.

For cases like the above, we must create a parent exception (or use an
existing one if it is appropriate) in order to convey that subclasses
_might_ throw exceptions that inherit from that one.
It this particular case, it seems that operators that are not positive
definite are illegal for method "solveInPlace", hence we conclude (not
surprisingly) that "MathIllegalArgumentException" can be thrown from classes
that implement "RealLinearOperator.solveInPlace".

In fact, this is even too much of a "guessing" work. And this where a single
root can be used to clearly advertize that, by design, CM is supposed to
throw only (subclasses of) "MathRunimeException". _That_ exception, and
_nothing_ else should really be inserted in the "throws" clause of upper
level base classes and interfaces.

Referring to the above example, it is the duty of the user of CM to read the
documentation of the (concrete) classes he uses if he wants to know which
subclass of "MathRuntimeException" may actually be thrown; it is not enough
to read the documentation of the interface!
To be clear, CM will become a total clutter if upper levels attempt to
report everything all the way down. This is in blatant contradiction with
the principle (or rule, or best practice) of encapsulation.


Best regards,
Gilles

> > [...]

P.S. Practically, at this point, I propose to not touch interfaces or base
     classes, but only add the "throws" clauses where the methods actually
     throw the exceptions, and in some cases, one level up (where it is
     still obvious that a particular condition is required).
     Of course, that makes it impossible to test the "switch to checked
     exception" as the work is in progress. For this, let's wait until all
     the first pass has been completed, then we can see what is missing,
     and decide while seeing the picture.

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

Re: [math] Re: Single root for Exceptions

[Luc Maisonobe <Lu...@free.fr>]

Le 01/09/2012 10:42, Sébastien Brisard a écrit :
> Hi Luc,
> 
> 2012/9/1 Luc Maisonobe <Lu...@free.fr>:
>> Le 01/09/2012 10:03, Sébastien Brisard a écrit :
>>> Hi,
>>>
>>> in ConjugateGradient, I get the following error
>>>
>>> "Exception NonPositiveDefiniteOperatorException is not compatible with
>>> throws clause in
>>> PreconditionedIterativeLinearSolver.solveInPlace(RealLinearOperator,
>>> RealLinearOperator, RealVector, RealVector)"
>>>
>>> This comes from the fact that general iterative solvers do not require
>>> positive definite operators (therefore, no
>>> "throws NonPositiveDefiniteOperatorException" clause in the signature of
>>> PreconditionedIterativeLinearSolver.solveInPlace), while conjugate
>>> gradient does.
>>>
>>> Do I need to add the "throws NonPositiveDefiniteOperatorException"
>>> clause in the signature of
>>> PreconditionedIterativeLinearSolver.solveInPlace as well?
>>
>> I think so, as users may use a ConjugateGradient and store it in a
>> variable declared with the base class only. However, I don't know if
>> adding an unchecked exception to the signature of an interface is a
>> compatible change or not.
>>
>> Luc
>>
> clirr does not seem to be complaining, so I'll do as you say. Here is
> what I'm planning to add to the javadoc of the mother abstract class.
> What do you think?
> 
>      * @throws NonPositiveDefiniteOperatorException if {@code a} or {@code m}
>      * is not positive definite (required by some iterative solvers)

Perfect!

thanks,

Luc

> 
> 
> Sébastien
> 
>>>
>>> Sébastien
>>>
>>> 2012/9/1 Sébastien Brisard <se...@m4x.org>:
>>>> Hello,
>>>>
>>>>
>>>> 2012/8/31 Thomas Neidhart <th...@gmail.com>:
>>>>> On 08/31/2012 11:17 AM, Luc Maisonobe wrote:
>>>>>> Le 31/08/2012 03:22, Sébastien Brisard a écrit :
>>>>>>> Hello,
>>>>>>>
>>>>>>>>>>> [...]
>>>>>>>>>>>
>>>>>>>>>>> Thus, shall I open a JIRA ticket with the tasks of completing the "throws"
>>>>>>>>>>> clauses of all CM methods?
>>>>>>>>>>> Does someone absolutely needs this task tobe completed before releasing 3.1?
>>>>>>>>>>> [I don't think that it's possible without a huge effort from everyone.]
>>>>>>>>>
>>>>>>>>> Ticket created:
>>>>>>>>>  https://issues.apache.org/jira/browse/MATH-854
>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>> No hurry on my side, but I'm happy contributing. In order not to tread
>>>>>>>>>> on anyone's feet, maybe each of us should be assigned one package (for
>>>>>>>>>> a start).
>>>>>>>>>
>>>>>>>>> Good idea.
>>>>>>>>>
>>>>>>>>> Gilles: packages "o.a.c.m.optimization"
>>>>>>>>>                 "o.a.c.m.analysis.function"
>>>>>>>>>                 "o.a.c.m.analysis.solvers"
>>>>>>>>>                 "o.a.c.m.analysis.integration"
>>>>>>>>>                 "o.a.c.m.analysis.interpolation"
>>>>>>>>
>>>>>>>> +1 to divide and conquer.  I will start on stat.
>>>>>>>>
>>>>>>>> Phil
>>>>>>>>>
>>>>>>>>>
>>>>>>>>> Best regards,
>>>>>>>>> Gilles
>>>>>>>>>
>>>>>>> I can take care of linear and special, of course!
>>>>>>
>>>>>> I'll look at ode, differentiation and geometry.
>>>>>
>>>>> I will start with filter and genetics.
>>>>>
>>>>> Thomas
>>>>>
>>>> Just to make sure I don't forget anything... We must apply
>>>> you-know-who's trick to 4 and only 4 exception types
>>>>   - MathArithmeticException
>>>>   - MathIllegalArgumentException
>>>>   - MathIllegalStateException
>>>>   - MathUnsupportedOperationException
>>>>
>>>> Is that correct?
>>>> Sébastien
>>>
>>>
>>> ---------------------------------------------------------------------
>>> 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
>>
> 
> 
> ---------------------------------------------------------------------
> 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

Re: [math] Re: Single root for Exceptions

[Sébastien Brisard <se...@m4x.org>]

Hi Luc,

2012/9/1 Luc Maisonobe <Lu...@free.fr>:
> Le 01/09/2012 10:03, Sébastien Brisard a écrit :
>> Hi,
>>
>> in ConjugateGradient, I get the following error
>>
>> "Exception NonPositiveDefiniteOperatorException is not compatible with
>> throws clause in
>> PreconditionedIterativeLinearSolver.solveInPlace(RealLinearOperator,
>> RealLinearOperator, RealVector, RealVector)"
>>
>> This comes from the fact that general iterative solvers do not require
>> positive definite operators (therefore, no
>> "throws NonPositiveDefiniteOperatorException" clause in the signature of
>> PreconditionedIterativeLinearSolver.solveInPlace), while conjugate
>> gradient does.
>>
>> Do I need to add the "throws NonPositiveDefiniteOperatorException"
>> clause in the signature of
>> PreconditionedIterativeLinearSolver.solveInPlace as well?
>
> I think so, as users may use a ConjugateGradient and store it in a
> variable declared with the base class only. However, I don't know if
> adding an unchecked exception to the signature of an interface is a
> compatible change or not.
>
> Luc
>
clirr does not seem to be complaining, so I'll do as you say. Here is
what I'm planning to add to the javadoc of the mother abstract class.
What do you think?

     * @throws NonPositiveDefiniteOperatorException if {@code a} or {@code m}
     * is not positive definite (required by some iterative solvers)


Sébastien

>>
>> Sébastien
>>
>> 2012/9/1 Sébastien Brisard <se...@m4x.org>:
>>> Hello,
>>>
>>>
>>> 2012/8/31 Thomas Neidhart <th...@gmail.com>:
>>>> On 08/31/2012 11:17 AM, Luc Maisonobe wrote:
>>>>> Le 31/08/2012 03:22, Sébastien Brisard a écrit :
>>>>>> Hello,
>>>>>>
>>>>>>>>>> [...]
>>>>>>>>>>
>>>>>>>>>> Thus, shall I open a JIRA ticket with the tasks of completing the "throws"
>>>>>>>>>> clauses of all CM methods?
>>>>>>>>>> Does someone absolutely needs this task tobe completed before releasing 3.1?
>>>>>>>>>> [I don't think that it's possible without a huge effort from everyone.]
>>>>>>>>
>>>>>>>> Ticket created:
>>>>>>>>  https://issues.apache.org/jira/browse/MATH-854
>>>>>>>>
>>>>>>>>>>
>>>>>>>>>
>>>>>>>>> No hurry on my side, but I'm happy contributing. In order not to tread
>>>>>>>>> on anyone's feet, maybe each of us should be assigned one package (for
>>>>>>>>> a start).
>>>>>>>>
>>>>>>>> Good idea.
>>>>>>>>
>>>>>>>> Gilles: packages "o.a.c.m.optimization"
>>>>>>>>                 "o.a.c.m.analysis.function"
>>>>>>>>                 "o.a.c.m.analysis.solvers"
>>>>>>>>                 "o.a.c.m.analysis.integration"
>>>>>>>>                 "o.a.c.m.analysis.interpolation"
>>>>>>>
>>>>>>> +1 to divide and conquer.  I will start on stat.
>>>>>>>
>>>>>>> Phil
>>>>>>>>
>>>>>>>>
>>>>>>>> Best regards,
>>>>>>>> Gilles
>>>>>>>>
>>>>>> I can take care of linear and special, of course!
>>>>>
>>>>> I'll look at ode, differentiation and geometry.
>>>>
>>>> I will start with filter and genetics.
>>>>
>>>> Thomas
>>>>
>>> Just to make sure I don't forget anything... We must apply
>>> you-know-who's trick to 4 and only 4 exception types
>>>   - MathArithmeticException
>>>   - MathIllegalArgumentException
>>>   - MathIllegalStateException
>>>   - MathUnsupportedOperationException
>>>
>>> Is that correct?
>>> Sébastien
>>
>>
>> ---------------------------------------------------------------------
>> 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
>


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

Re: [math] Re: Single root for Exceptions

[Luc Maisonobe <Lu...@free.fr>]

Le 01/09/2012 10:03, Sébastien Brisard a écrit :
> Hi,
> 
> in ConjugateGradient, I get the following error
> 
> "Exception NonPositiveDefiniteOperatorException is not compatible with
> throws clause in
> PreconditionedIterativeLinearSolver.solveInPlace(RealLinearOperator,
> RealLinearOperator, RealVector, RealVector)"
> 
> This comes from the fact that general iterative solvers do not require
> positive definite operators (therefore, no
> "throws NonPositiveDefiniteOperatorException" clause in the signature of
> PreconditionedIterativeLinearSolver.solveInPlace), while conjugate
> gradient does.
> 
> Do I need to add the "throws NonPositiveDefiniteOperatorException"
> clause in the signature of
> PreconditionedIterativeLinearSolver.solveInPlace as well?

I think so, as users may use a ConjugateGradient and store it in a
variable declared with the base class only. However, I don't know if
adding an unchecked exception to the signature of an interface is a
compatible change or not.

Luc

> 
> Sébastien
> 
> 2012/9/1 Sébastien Brisard <se...@m4x.org>:
>> Hello,
>>
>>
>> 2012/8/31 Thomas Neidhart <th...@gmail.com>:
>>> On 08/31/2012 11:17 AM, Luc Maisonobe wrote:
>>>> Le 31/08/2012 03:22, Sébastien Brisard a écrit :
>>>>> Hello,
>>>>>
>>>>>>>>> [...]
>>>>>>>>>
>>>>>>>>> Thus, shall I open a JIRA ticket with the tasks of completing the "throws"
>>>>>>>>> clauses of all CM methods?
>>>>>>>>> Does someone absolutely needs this task tobe completed before releasing 3.1?
>>>>>>>>> [I don't think that it's possible without a huge effort from everyone.]
>>>>>>>
>>>>>>> Ticket created:
>>>>>>>  https://issues.apache.org/jira/browse/MATH-854
>>>>>>>
>>>>>>>>>
>>>>>>>>
>>>>>>>> No hurry on my side, but I'm happy contributing. In order not to tread
>>>>>>>> on anyone's feet, maybe each of us should be assigned one package (for
>>>>>>>> a start).
>>>>>>>
>>>>>>> Good idea.
>>>>>>>
>>>>>>> Gilles: packages "o.a.c.m.optimization"
>>>>>>>                 "o.a.c.m.analysis.function"
>>>>>>>                 "o.a.c.m.analysis.solvers"
>>>>>>>                 "o.a.c.m.analysis.integration"
>>>>>>>                 "o.a.c.m.analysis.interpolation"
>>>>>>
>>>>>> +1 to divide and conquer.  I will start on stat.
>>>>>>
>>>>>> Phil
>>>>>>>
>>>>>>>
>>>>>>> Best regards,
>>>>>>> Gilles
>>>>>>>
>>>>> I can take care of linear and special, of course!
>>>>
>>>> I'll look at ode, differentiation and geometry.
>>>
>>> I will start with filter and genetics.
>>>
>>> Thomas
>>>
>> Just to make sure I don't forget anything... We must apply
>> you-know-who's trick to 4 and only 4 exception types
>>   - MathArithmeticException
>>   - MathIllegalArgumentException
>>   - MathIllegalStateException
>>   - MathUnsupportedOperationException
>>
>> Is that correct?
>> Sébastien
> 
> 
> ---------------------------------------------------------------------
> 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

Re: [math] Re: Single root for Exceptions

[Sébastien Brisard <se...@m4x.org>]

Hi,

in ConjugateGradient, I get the following error

"Exception NonPositiveDefiniteOperatorException is not compatible with
throws clause in
PreconditionedIterativeLinearSolver.solveInPlace(RealLinearOperator,
RealLinearOperator, RealVector, RealVector)"

This comes from the fact that general iterative solvers do not require
positive definite operators (therefore, no
"throws NonPositiveDefiniteOperatorException" clause in the signature of
PreconditionedIterativeLinearSolver.solveInPlace), while conjugate
gradient does.

Do I need to add the "throws NonPositiveDefiniteOperatorException"
clause in the signature of
PreconditionedIterativeLinearSolver.solveInPlace as well?

Sébastien

2012/9/1 Sébastien Brisard <se...@m4x.org>:
> Hello,
>
>
> 2012/8/31 Thomas Neidhart <th...@gmail.com>:
>> On 08/31/2012 11:17 AM, Luc Maisonobe wrote:
>>> Le 31/08/2012 03:22, Sébastien Brisard a écrit :
>>>> Hello,
>>>>
>>>>>>>> [...]
>>>>>>>>
>>>>>>>> Thus, shall I open a JIRA ticket with the tasks of completing the "throws"
>>>>>>>> clauses of all CM methods?
>>>>>>>> Does someone absolutely needs this task tobe completed before releasing 3.1?
>>>>>>>> [I don't think that it's possible without a huge effort from everyone.]
>>>>>>
>>>>>> Ticket created:
>>>>>>  https://issues.apache.org/jira/browse/MATH-854
>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>> No hurry on my side, but I'm happy contributing. In order not to tread
>>>>>>> on anyone's feet, maybe each of us should be assigned one package (for
>>>>>>> a start).
>>>>>>
>>>>>> Good idea.
>>>>>>
>>>>>> Gilles: packages "o.a.c.m.optimization"
>>>>>>                 "o.a.c.m.analysis.function"
>>>>>>                 "o.a.c.m.analysis.solvers"
>>>>>>                 "o.a.c.m.analysis.integration"
>>>>>>                 "o.a.c.m.analysis.interpolation"
>>>>>
>>>>> +1 to divide and conquer.  I will start on stat.
>>>>>
>>>>> Phil
>>>>>>
>>>>>>
>>>>>> Best regards,
>>>>>> Gilles
>>>>>>
>>>> I can take care of linear and special, of course!
>>>
>>> I'll look at ode, differentiation and geometry.
>>
>> I will start with filter and genetics.
>>
>> Thomas
>>
> Just to make sure I don't forget anything... We must apply
> you-know-who's trick to 4 and only 4 exception types
>   - MathArithmeticException
>   - MathIllegalArgumentException
>   - MathIllegalStateException
>   - MathUnsupportedOperationException
>
> Is that correct?
> Sébastien


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

Re: [math] Re: Single root for Exceptions

[Sébastien Brisard <se...@m4x.org>]

Hello,


2012/8/31 Thomas Neidhart <th...@gmail.com>:
> On 08/31/2012 11:17 AM, Luc Maisonobe wrote:
>> Le 31/08/2012 03:22, Sébastien Brisard a écrit :
>>> Hello,
>>>
>>>>>>> [...]
>>>>>>>
>>>>>>> Thus, shall I open a JIRA ticket with the tasks of completing the "throws"
>>>>>>> clauses of all CM methods?
>>>>>>> Does someone absolutely needs this task tobe completed before releasing 3.1?
>>>>>>> [I don't think that it's possible without a huge effort from everyone.]
>>>>>
>>>>> Ticket created:
>>>>>  https://issues.apache.org/jira/browse/MATH-854
>>>>>
>>>>>>>
>>>>>>
>>>>>> No hurry on my side, but I'm happy contributing. In order not to tread
>>>>>> on anyone's feet, maybe each of us should be assigned one package (for
>>>>>> a start).
>>>>>
>>>>> Good idea.
>>>>>
>>>>> Gilles: packages "o.a.c.m.optimization"
>>>>>                 "o.a.c.m.analysis.function"
>>>>>                 "o.a.c.m.analysis.solvers"
>>>>>                 "o.a.c.m.analysis.integration"
>>>>>                 "o.a.c.m.analysis.interpolation"
>>>>
>>>> +1 to divide and conquer.  I will start on stat.
>>>>
>>>> Phil
>>>>>
>>>>>
>>>>> Best regards,
>>>>> Gilles
>>>>>
>>> I can take care of linear and special, of course!
>>
>> I'll look at ode, differentiation and geometry.
>
> I will start with filter and genetics.
>
> Thomas
>
Just to make sure I don't forget anything... We must apply
you-know-who's trick to 4 and only 4 exception types
  - MathArithmeticException
  - MathIllegalArgumentException
  - MathIllegalStateException
  - MathUnsupportedOperationException

Is that correct?
Sébastien


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

Re: [math] Re: Single root for Exceptions

[Thomas Neidhart <th...@gmail.com>]

On 08/31/2012 11:17 AM, Luc Maisonobe wrote:
> Le 31/08/2012 03:22, Sébastien Brisard a écrit :
>> Hello,
>>
>>>>>> [...]
>>>>>>
>>>>>> Thus, shall I open a JIRA ticket with the tasks of completing the "throws"
>>>>>> clauses of all CM methods?
>>>>>> Does someone absolutely needs this task tobe completed before releasing 3.1?
>>>>>> [I don't think that it's possible without a huge effort from everyone.]
>>>>
>>>> Ticket created:
>>>>  https://issues.apache.org/jira/browse/MATH-854
>>>>
>>>>>>
>>>>>
>>>>> No hurry on my side, but I'm happy contributing. In order not to tread
>>>>> on anyone's feet, maybe each of us should be assigned one package (for
>>>>> a start).
>>>>
>>>> Good idea.
>>>>
>>>> Gilles: packages "o.a.c.m.optimization"
>>>>                 "o.a.c.m.analysis.function"
>>>>                 "o.a.c.m.analysis.solvers"
>>>>                 "o.a.c.m.analysis.integration"
>>>>                 "o.a.c.m.analysis.interpolation"
>>>
>>> +1 to divide and conquer.  I will start on stat.
>>>
>>> Phil
>>>>
>>>>
>>>> Best regards,
>>>> Gilles
>>>>
>> I can take care of linear and special, of course!
> 
> I'll look at ode, differentiation and geometry.

I will start with filter and genetics.

Thomas

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

Re: [math] Re: Single root for Exceptions

[Luc Maisonobe <Lu...@free.fr>]

Le 31/08/2012 03:22, Sébastien Brisard a écrit :
> Hello,
> 
>>>>> [...]
>>>>>
>>>>> Thus, shall I open a JIRA ticket with the tasks of completing the "throws"
>>>>> clauses of all CM methods?
>>>>> Does someone absolutely needs this task tobe completed before releasing 3.1?
>>>>> [I don't think that it's possible without a huge effort from everyone.]
>>>
>>> Ticket created:
>>>  https://issues.apache.org/jira/browse/MATH-854
>>>
>>>>>
>>>>
>>>> No hurry on my side, but I'm happy contributing. In order not to tread
>>>> on anyone's feet, maybe each of us should be assigned one package (for
>>>> a start).
>>>
>>> Good idea.
>>>
>>> Gilles: packages "o.a.c.m.optimization"
>>>                 "o.a.c.m.analysis.function"
>>>                 "o.a.c.m.analysis.solvers"
>>>                 "o.a.c.m.analysis.integration"
>>>                 "o.a.c.m.analysis.interpolation"
>>
>> +1 to divide and conquer.  I will start on stat.
>>
>> Phil
>>>
>>>
>>> Best regards,
>>> Gilles
>>>
> I can take care of linear and special, of course!

I'll look at ode, differentiation and geometry.

Luc

> Sébastien
> 
> 
> ---------------------------------------------------------------------
> 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

Re: [math] Re: Single root for Exceptions

[Sébastien Brisard <se...@m4x.org>]

Hello,

>>>> [...]
>>>>
>>>> Thus, shall I open a JIRA ticket with the tasks of completing the "throws"
>>>> clauses of all CM methods?
>>>> Does someone absolutely needs this task tobe completed before releasing 3.1?
>>>> [I don't think that it's possible without a huge effort from everyone.]
>>
>> Ticket created:
>>  https://issues.apache.org/jira/browse/MATH-854
>>
>>>>
>>>
>>> No hurry on my side, but I'm happy contributing. In order not to tread
>>> on anyone's feet, maybe each of us should be assigned one package (for
>>> a start).
>>
>> Good idea.
>>
>> Gilles: packages "o.a.c.m.optimization"
>>                 "o.a.c.m.analysis.function"
>>                 "o.a.c.m.analysis.solvers"
>>                 "o.a.c.m.analysis.integration"
>>                 "o.a.c.m.analysis.interpolation"
>
> +1 to divide and conquer.  I will start on stat.
>
> Phil
>>
>>
>> Best regards,
>> Gilles
>>
I can take care of linear and special, of course!
Sébastien


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

Re: [math] Re: Single root for Exceptions

[Phil Steitz <ph...@gmail.com>]

On Aug 30, 2012, at 4:56 AM, Gilles Sadowski <gi...@harfang.homelinux.org> wrote:

>>> [...]
>>> 
>>> Thus, shall I open a JIRA ticket with the tasks of completing the "throws"
>>> clauses of all CM methods?
>>> Does someone absolutely needs this task tobe completed before releasing 3.1?
>>> [I don't think that it's possible without a huge effort from everyone.]
> 
> Ticket created:
>  https://issues.apache.org/jira/browse/MATH-854
> 
>>> 
>> 
>> No hurry on my side, but I'm happy contributing. In order not to tread
>> on anyone's feet, maybe each of us should be assigned one package (for
>> a start).
> 
> Good idea.
> 
> Gilles: packages "o.a.c.m.optimization"
>                 "o.a.c.m.analysis.function"
>                 "o.a.c.m.analysis.solvers"
>                 "o.a.c.m.analysis.integration"
>                 "o.a.c.m.analysis.interpolation"

+1 to divide and conquer.  I will start on stat.

Phil
> 
> 
> Best 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

Re: [math] Re: Single root for Exceptions

[Gilles Sadowski <gi...@harfang.homelinux.org>]

> > [...]
> >
> > Thus, shall I open a JIRA ticket with the tasks of completing the "throws"
> > clauses of all CM methods?
> > Does someone absolutely needs this task tobe completed before releasing 3.1?
> > [I don't think that it's possible without a huge effort from everyone.]

Ticket created:
  https://issues.apache.org/jira/browse/MATH-854

> >
> 
> No hurry on my side, but I'm happy contributing. In order not to tread
> on anyone's feet, maybe each of us should be assigned one package (for
> a start).

Good idea.

Gilles: packages "o.a.c.m.optimization"
                 "o.a.c.m.analysis.function"
                 "o.a.c.m.analysis.solvers"
                 "o.a.c.m.analysis.integration"
                 "o.a.c.m.analysis.interpolation"


Best regards,
Gilles

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

Re: [math] Re: Single root for Exceptions

[Gilles Sadowski <gi...@harfang.homelinux.org>]

> >> [...]
> > I think we had a discussion a few months ago on how exceptions should
> > be documented. We came to no agreement at that time, although one
> > option (which I followed) was to
> >   - remove unchecked exceptions from the method's signature
> >   - add the unchecjked exceptions to the javadoc.
> > I agree we should make sure that all exceptions are advertised in the
> > javadoc. However, I don't see how Luc's trick can help us in this case
> > (if we agree that exceptions should *not* appear in the signature). Am
> > I missing something?
> 
> No, you are not missing anything. Having only the javadoc without the
> declaration in the signature is a pain. I would prefer to keep both. As
> I said earlier in this thread, I gave up on the discussion at some time
> and did not participate to the last occurrence you point out. I thought
> I served a lost cause then.

Luc,

I think that you are confusing two discussions. One was about the final step
of the overhaul of the exceptions, where Phil preferred (among other things)
to have multiple hierarchies (in order to be able to catch separately the
Java standard exceptions) instead of the "MathRuntimeException" on which you
and I had agreed.
The discussion which Sébastien refers to is much more recent and relates to
source code style (indeed) where at the time I said that the "throws" clause
should not be included in the signature for unchecked exceptions but solely
in the Javadoc (in line with the recommendations of "Effective Java").
[I've know changed my mind on this (for CM only, as I still think that, in
general, it is nicer to not have redundant information).]


Regards,
Gilles

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

Re: [math] Re: Single root for Exceptions

[Sébastien Brisard <se...@m4x.org>]

Hi,

2012/8/30 Gilles Sadowski <gi...@harfang.homelinux.org>:
> On Wed, Aug 29, 2012 at 06:33:05PM -0700, Phil Steitz wrote:
>> On 8/29/12 3:04 PM, Gilles Sadowski wrote:
>> > Hello.
>> >
>> > To summarize:
>> >  (1) Does anyone disagree with having all CM exceptions inherit
>> >      from a new "MathRuntimeException" which itself will inherit
>> >      from the standard "RuntimeException"?
>> +0
>> >  (2) Does anyone disagree with all exceptions being mandatorily
>> >      advertized in the "throws" clause of methods and constructors?
>> >      That means that for each exception explicitly instantiated in the
>> >      body of the method, the instantiated type must appear in "throws"
>> >      clause.
>> +1 - though I am OK advertising superclasses in cases where that is
>> appropriate (but not to the point of (3) below)
>> >  (3) Does anyone disagree that the "throws" clause of a method could
>> >      advertize "MathRuntimeException" for any exception not thrown by
>> >      itself but by a method which it calls?
>> >      That means that it is not mandatory to indicate the specific type
>> >      for exceptions not explicitly instantiated in the body the current
>> >      method.
>> -1
>> In general, we should avoid that, because it is equivalent to
>> "throws Exception." The exceptions that a method in the public
>> [math] API propagates should be documented and advertised by it.
>> Which exceptions a method itself generates is an implementation
>> artifact.  What is important in the API is what exceptions the
>> caller is going to see.
>
> You are right. As I said, I was not sure that would be a good rule.
> [Also I don't think that there are many cases where exceptions are propagated
> from lower levels without being advertized in relation to the current
> context.]
>
> Thus, shall I open a JIRA ticket with the tasks of completing the "throws"
> clauses of all CM methods?
> Does someone absolutely needs this task tobe completed before releasing 3.1?
> [I don't think that it's possible without a huge effort from everyone.]
>

No hurry on my side, but I'm happy contributing. In order not to tread
on anyone's feet, maybe each of us should be assigned one package (for
a start).
S

>
> Regards,
> Gilles
>
>>
>> Phil
>> >
>> >
>> > I'm not sure about point (3); it seems that it would avoid duplicating
>> > descriptions of lower-level preconditions for CM methods that calls other CM
>> > methods or advertizing something that would be an implementation detail for
>> > the calling method. I didn't check how often that would apply...
>> > At first sight, that would surely avoid that upper levels are tightly
>> > coupled to lower levels: if a method is modified to throw a new exception,
>> > methods that call it do not have to update their documentation and "throws"
>> > clause.
>> >
>> >
>> > 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

Re: [math] Re: Single root for Exceptions

[Gilles Sadowski <gi...@harfang.homelinux.org>]

On Wed, Aug 29, 2012 at 06:33:05PM -0700, Phil Steitz wrote:
> On 8/29/12 3:04 PM, Gilles Sadowski wrote:
> > Hello.
> >
> > To summarize:
> >  (1) Does anyone disagree with having all CM exceptions inherit
> >      from a new "MathRuntimeException" which itself will inherit
> >      from the standard "RuntimeException"?
> +0
> >  (2) Does anyone disagree with all exceptions being mandatorily
> >      advertized in the "throws" clause of methods and constructors?
> >      That means that for each exception explicitly instantiated in the
> >      body of the method, the instantiated type must appear in "throws"
> >      clause.
> +1 - though I am OK advertising superclasses in cases where that is
> appropriate (but not to the point of (3) below)
> >  (3) Does anyone disagree that the "throws" clause of a method could
> >      advertize "MathRuntimeException" for any exception not thrown by
> >      itself but by a method which it calls?
> >      That means that it is not mandatory to indicate the specific type
> >      for exceptions not explicitly instantiated in the body the current
> >      method.
> -1
> In general, we should avoid that, because it is equivalent to
> "throws Exception." The exceptions that a method in the public
> [math] API propagates should be documented and advertised by it. 
> Which exceptions a method itself generates is an implementation
> artifact.  What is important in the API is what exceptions the
> caller is going to see.  

You are right. As I said, I was not sure that would be a good rule.
[Also I don't think that there are many cases where exceptions are propagated
from lower levels without being advertized in relation to the current
context.]

Thus, shall I open a JIRA ticket with the tasks of completing the "throws"
clauses of all CM methods?
Does someone absolutely needs this task tobe completed before releasing 3.1?
[I don't think that it's possible without a huge effort from everyone.]


Regards,
Gilles

> 
> Phil
> >
> >
> > I'm not sure about point (3); it seems that it would avoid duplicating
> > descriptions of lower-level preconditions for CM methods that calls other CM
> > methods or advertizing something that would be an implementation detail for
> > the calling method. I didn't check how often that would apply...
> > At first sight, that would surely avoid that upper levels are tightly
> > coupled to lower levels: if a method is modified to throw a new exception,
> > methods that call it do not have to update their documentation and "throws"
> > clause.
> >
> >
> > Regards,
> > Gilles

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

Re: [math] Re: Single root for Exceptions

[Phil Steitz <ph...@gmail.com>]

On 8/29/12 3:04 PM, Gilles Sadowski wrote:
> Hello.
>
> To summarize:
>  (1) Does anyone disagree with having all CM exceptions inherit
>      from a new "MathRuntimeException" which itself will inherit
>      from the standard "RuntimeException"?
+0
>  (2) Does anyone disagree with all exceptions being mandatorily
>      advertized in the "throws" clause of methods and constructors?
>      That means that for each exception explicitly instantiated in the
>      body of the method, the instantiated type must appear in "throws"
>      clause.
+1 - though I am OK advertising superclasses in cases where that is
appropriate (but not to the point of (3) below)
>  (3) Does anyone disagree that the "throws" clause of a method could
>      advertize "MathRuntimeException" for any exception not thrown by
>      itself but by a method which it calls?
>      That means that it is not mandatory to indicate the specific type
>      for exceptions not explicitly instantiated in the body the current
>      method.
-1
In general, we should avoid that, because it is equivalent to
"throws Exception." The exceptions that a method in the public
[math] API propagates should be documented and advertised by it. 
Which exceptions a method itself generates is an implementation
artifact.  What is important in the API is what exceptions the
caller is going to see.  

Phil
>
>
> I'm not sure about point (3); it seems that it would avoid duplicating
> descriptions of lower-level preconditions for CM methods that calls other CM
> methods or advertizing something that would be an implementation detail for
> the calling method. I didn't check how often that would apply...
> At first sight, that would surely avoid that upper levels are tightly
> coupled to lower levels: if a method is modified to throw a new exception,
> methods that call it do not have to update their documentation and "throws"
> clause.
>
>
> 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

Re: [math] Re: Single root for Exceptions

[Thomas Neidhart <th...@gmail.com>]

On 08/30/2012 12:41 PM, Luc Maisonobe wrote:
> Le 30/08/2012 05:08, Sébastien Brisard a écrit :
>> Hello,

Hi,

sorry, I did not participate much in the discussion.

>> 2012/8/30 Gilles Sadowski <gi...@harfang.homelinux.org>:
>>> Hello.
>>>
>>> To summarize:
>>>  (1) Does anyone disagree with having all CM exceptions inherit
>>>      from a new "MathRuntimeException" which itself will inherit
>>>      from the standard "RuntimeException"?
>> +0: my background is not good enough.
> 
> +1

+0

>>>  (2) Does anyone disagree with all exceptions being mandatorily
>>>      advertized in the "throws" clause of methods and constructors?
>>>      That means that for each exception explicitly instantiated in the
>>>      body of the method, the instantiated type must appear in "throws"
>>>      clause.
> 
> +1

+1

>>>  (3) Does anyone disagree that the "throws" clause of a method could
>>>      advertize "MathRuntimeException" for any exception not thrown by
>>>      itself but by a method which it calls?
>>>      That means that it is not mandatory to indicate the specific type
>>>      for exceptions not explicitly instantiated in the body the current
>>>      method.
>>>
>>>
>>> I'm not sure about point (3); it seems that it would avoid duplicating
>>> descriptions of lower-level preconditions for CM methods that calls other CM
>>> methods or advertizing something that would be an implementation detail for
>>> the calling method. I didn't check how often that would apply...
>>> At first sight, that would surely avoid that upper levels are tightly
>>> coupled to lower levels: if a method is modified to throw a new exception,
>>> methods that call it do not have to update their documentation and "throws"
>>> clause.
>>>
>> -0: I don't like the idea of advertising such a general exception, but
>> again, I lack the general background in computer science. Maybe we
>> could ask ourselves two questions
>> 1. If, when changing the implementation of a method, it turns out that
>> an exception is no longer thrown, or a new one is thrown, does this
>> break compatibility?
>> 2. Surely, there are two cases about exceptions thrown by a method
>> called within the method under consideration.
>>   2a. If the exception is raised by a method called by an object the
>> end-user knows, e.g
>>
>> public ReturnType theMethod(final ParamType x) {
>>     // I am going to throw an exception
>>     theOtherMethod(x);
>> }
>>
>> in this case, the exception might still be meaningful to the end user
>>
>>   2b. if the exception is raised by a method called with an object the
>> end-user doesn't know
>>
>> public ReturnType theMethod(final ParamType x) {
>>
>>     final AnotherType y = ...
>>     // I am going to throw an exception
>>     theOtherMethod(y);
>> }
>>
>> in this case, the exception might not be so meaningful, and maybe
>> advertising MRE would be sufficient (although I still do not really
>> like that).
>>
>> Cases 2a and 2b might well be not so clear cut. E. g. what do we do
>> with method calls like theOtherMethod(x, y)? So I would be slightly in
>> favor of precisely advertizing every single exception.
> 
> I think we must advertise them, as long as they are thrown by [maht]
> itself. Either we do the work all the way through or we don't do it.
> Stopping at the first level of public API would be wasting our time
> without benefits. Exceptions do propagate, if we need to know they are
> thrown, we need it all the way through. If we decide its too much work,
> then we should not bother doing it even on first call level.

I agree here with the comment of Luc, either we do it full-way or leave
it as it is now.

Thomas

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

Re: [math] Re: Single root for Exceptions

[Luc Maisonobe <Lu...@free.fr>]

Le 30/08/2012 05:08, Sébastien Brisard a écrit :
> Hello,
> 
> 2012/8/30 Gilles Sadowski <gi...@harfang.homelinux.org>:
>> Hello.
>>
>> To summarize:
>>  (1) Does anyone disagree with having all CM exceptions inherit
>>      from a new "MathRuntimeException" which itself will inherit
>>      from the standard "RuntimeException"?
> +0: my background is not good enough.

+1

>>  (2) Does anyone disagree with all exceptions being mandatorily
>>      advertized in the "throws" clause of methods and constructors?
>>      That means that for each exception explicitly instantiated in the
>>      body of the method, the instantiated type must appear in "throws"
>>      clause.

+1
> +1, if only for the sake of the so-called "Luc's trick" (@Luc:
> something's called your name, that's the beginning of celebrity ;)

-1 to it being named Luc's trick :-(

> !!!).
>>  (3) Does anyone disagree that the "throws" clause of a method could
>>      advertize "MathRuntimeException" for any exception not thrown by
>>      itself but by a method which it calls?
>>      That means that it is not mandatory to indicate the specific type
>>      for exceptions not explicitly instantiated in the body the current
>>      method.
>>
>>
>> I'm not sure about point (3); it seems that it would avoid duplicating
>> descriptions of lower-level preconditions for CM methods that calls other CM
>> methods or advertizing something that would be an implementation detail for
>> the calling method. I didn't check how often that would apply...
>> At first sight, that would surely avoid that upper levels are tightly
>> coupled to lower levels: if a method is modified to throw a new exception,
>> methods that call it do not have to update their documentation and "throws"
>> clause.
>>
> -0: I don't like the idea of advertising such a general exception, but
> again, I lack the general background in computer science. Maybe we
> could ask ourselves two questions
> 1. If, when changing the implementation of a method, it turns out that
> an exception is no longer thrown, or a new one is thrown, does this
> break compatibility?
> 2. Surely, there are two cases about exceptions thrown by a method
> called within the method under consideration.
>   2a. If the exception is raised by a method called by an object the
> end-user knows, e.g
> 
> public ReturnType theMethod(final ParamType x) {
>     // I am going to throw an exception
>     theOtherMethod(x);
> }
> 
> in this case, the exception might still be meaningful to the end user
> 
>   2b. if the exception is raised by a method called with an object the
> end-user doesn't know
> 
> public ReturnType theMethod(final ParamType x) {
> 
>     final AnotherType y = ...
>     // I am going to throw an exception
>     theOtherMethod(y);
> }
> 
> in this case, the exception might not be so meaningful, and maybe
> advertising MRE would be sufficient (although I still do not really
> like that).
> 
> Cases 2a and 2b might well be not so clear cut. E. g. what do we do
> with method calls like theOtherMethod(x, y)? So I would be slightly in
> favor of precisely advertizing every single exception.

I think we must advertise them, as long as they are thrown by [maht]
itself. Either we do the work all the way through or we don't do it.
Stopping at the first level of public API would be wasting our time
without benefits. Exceptions do propagate, if we need to know they are
thrown, we need it all the way through. If we decide its too much work,
then we should not bother doing it even on first call level.

Luc

> 
> These are just a few thoughts from someone which is not experienced in
> this field...
> 
> Sébastien
> 
> 
> ---------------------------------------------------------------------
> 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

Re: [math] Re: Single root for Exceptions

[Sébastien Brisard <se...@m4x.org>]

Hello,

2012/8/30 Gilles Sadowski <gi...@harfang.homelinux.org>:
> Hello.
>
> To summarize:
>  (1) Does anyone disagree with having all CM exceptions inherit
>      from a new "MathRuntimeException" which itself will inherit
>      from the standard "RuntimeException"?
+0: my background is not good enough.
>  (2) Does anyone disagree with all exceptions being mandatorily
>      advertized in the "throws" clause of methods and constructors?
>      That means that for each exception explicitly instantiated in the
>      body of the method, the instantiated type must appear in "throws"
>      clause.
+1, if only for the sake of the so-called "Luc's trick" (@Luc:
something's called your name, that's the beginning of celebrity ;)
!!!).
>  (3) Does anyone disagree that the "throws" clause of a method could
>      advertize "MathRuntimeException" for any exception not thrown by
>      itself but by a method which it calls?
>      That means that it is not mandatory to indicate the specific type
>      for exceptions not explicitly instantiated in the body the current
>      method.
>
>
> I'm not sure about point (3); it seems that it would avoid duplicating
> descriptions of lower-level preconditions for CM methods that calls other CM
> methods or advertizing something that would be an implementation detail for
> the calling method. I didn't check how often that would apply...
> At first sight, that would surely avoid that upper levels are tightly
> coupled to lower levels: if a method is modified to throw a new exception,
> methods that call it do not have to update their documentation and "throws"
> clause.
>
-0: I don't like the idea of advertising such a general exception, but
again, I lack the general background in computer science. Maybe we
could ask ourselves two questions
1. If, when changing the implementation of a method, it turns out that
an exception is no longer thrown, or a new one is thrown, does this
break compatibility?
2. Surely, there are two cases about exceptions thrown by a method
called within the method under consideration.
  2a. If the exception is raised by a method called by an object the
end-user knows, e.g

public ReturnType theMethod(final ParamType x) {
    // I am going to throw an exception
    theOtherMethod(x);
}

in this case, the exception might still be meaningful to the end user

  2b. if the exception is raised by a method called with an object the
end-user doesn't know

public ReturnType theMethod(final ParamType x) {

    final AnotherType y = ...
    // I am going to throw an exception
    theOtherMethod(y);
}

in this case, the exception might not be so meaningful, and maybe
advertising MRE would be sufficient (although I still do not really
like that).

Cases 2a and 2b might well be not so clear cut. E. g. what do we do
with method calls like theOtherMethod(x, y)? So I would be slightly in
favor of precisely advertizing every single exception.

These are just a few thoughts from someone which is not experienced in
this field...

Sébastien


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

Re: [math] Re: Single root for Exceptions

[Gilles Sadowski <gi...@harfang.homelinux.org>]

Hello.

To summarize:
 (1) Does anyone disagree with having all CM exceptions inherit
     from a new "MathRuntimeException" which itself will inherit
     from the standard "RuntimeException"?
 (2) Does anyone disagree with all exceptions being mandatorily
     advertized in the "throws" clause of methods and constructors?
     That means that for each exception explicitly instantiated in the
     body of the method, the instantiated type must appear in "throws"
     clause.
 (3) Does anyone disagree that the "throws" clause of a method could
     advertize "MathRuntimeException" for any exception not thrown by
     itself but by a method which it calls?
     That means that it is not mandatory to indicate the specific type
     for exceptions not explicitly instantiated in the body the current
     method.


I'm not sure about point (3); it seems that it would avoid duplicating
descriptions of lower-level preconditions for CM methods that calls other CM
methods or advertizing something that would be an implementation detail for
the calling method. I didn't check how often that would apply...
At first sight, that would surely avoid that upper levels are tightly
coupled to lower levels: if a method is modified to throw a new exception,
methods that call it do not have to update their documentation and "throws"
clause.


Regards,
Gilles

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

Re: [math] Re: Single root for Exceptions

[Gilles Sadowski <gi...@harfang.homelinux.org>]

> > No, you are not missing anything. Having only the javadoc without the
> > declaration in the signature is a pain. I would prefer to keep both. 
> 
> +1
> 
> Just "going boom" with an unadvertised RTE is not acceptable
> behavior.  We used to be very good about documenting and advertising
> all exceptions generated by [math].

The use of the past tense is not necessary. It's not because Luc found _one_
instance of a lacking documentation (in a code which he wrote) that the
current situation on this front is worse than it "used" to be.

>  I would very much like to see
> us get back to that level of API quality.

Again, please point to actual examples of lacking quality, especially in the
area of exceptions advertising.

[To point to just one example of (relatively minor, maybe, but actual) poor
quality, please have a look to the bugs/inconsistencies uncovered by
Sébastien in the area of sparse vectors.]

>  The fact that we can use
> Luc's trick to verify that we have not missed anything is enough to
> make me +1 for going back to a single root.

"Single root" and "Luc's trick" are totally unrelated.
Luc's trick only depends on having the exceptions appear in the throws
clause.
Single root is (sometimes) nicer for application developers (who do not have
to write multiple catch blocks).[1]


Gilles

[1] It is the same kind of "being nice to users" that was one of the main
    drives to get rid of checked exceptions (so that user code does not have
    to be riddled with either "try" blocks or "throws" clauses).

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

Re: [math] Re: Single root for Exceptions

[Phil Steitz <ph...@gmail.com>]

On 8/29/12 12:11 PM, Luc Maisonobe wrote:
> Le 29/08/2012 20:31, Sébastien Brisard a écrit :
>> Hello,
> Hi Sébastien,
>
>> 2012/8/29 Luc Maisonobe <Lu...@free.fr>:
>>> Le 29/08/2012 01:40, Gilles Sadowski a écrit :
>>>> Hi.
>>> Hello,
>>>
>>>>>> [...]
>>>>> I think I get your point, but again given transitive / nested
>>>>> dependencies I would not want to depend on it, even if all of the
>>>>> components have single-rooted exception hierarchies.  This is
>>>>> especially true if not all components adhere to the "wrap
>>>>> everything" rule - i.e., if they can generate and/or propagate RTEs
>>>>> that do not inherit from their base exception class.  From the
>>>>> standpoint of the caller, for example, what is the difference
>>>>> between [math]
>>>>>
>>>>> 0)  throwing IAE
>>>>> 1)  throwing MathIAE derived from IAE
>>>>> 2)  throwing MathIAE derived from MathRTE (base)
>>>>> assuming that [math] is not signing up to wrap and rethrow every
>>>>> exception - including IAE - we get from JDK classes?  Will the
>>> I was talking only about what we do throw ourselves.
>>>
>>>>> caller actually do anything different if the RTE is math-wrapped vs
>>>>> "naked" but coming out of the [math] code?  I understand that the
>>>>> try/catch may be several layers removed from the code calling a
>>>>> [math] API.
>>>>>
>>>>> Same applies to NPE, which we don't subclass now, but mostly handle
>>>>> as IAE.
>>>>>
>>>>> I guess one thing we might consider is trying to design for the
>>>>> invariant that we never propagate RTEs without wrapping.  But that
>>>>> would be a lot of work to retrofit and would have a performance cost.
>>>> I don't think that Luc means that we must wrap everyting in a home-made
>>>> exception.
>>> Gilles is right, I did not intend to catch and wrap everything.
>>>
>>>> Two possible cases for NPE:
>>>>  * The caller passed a "null" reference and will get, sooner or later, an
>>>>    NPE: it's a bug in his application.
>>>>  * An NPE was raised by a bug in CM, and we must fix it.
>>>>
>>>> I think that we should not check for "null" and thus have no use for an NPE
>>>> wrapper.
>>> I agree. We shouldn' wrap this.
>>>
>>>> Are there other "naked" exceptions that could come out of CM?
>>>> The policy of extensive precondition checking has the purpose (I think) to
>>>> prevent unexpected ("naked" or not) exceptions. If some slip through
>>>> nevertheless, doesn't it mean that we miss some check?
>>> I think we catch what we need to catch and already have a ggod deal of
>>> checking. Of course, we surely missed a few cases, we will fix them when
>>> they are identified.
>>>
>>>>>> Another problem is maintenance. Even if you consider the intermediate
>>>>>> developer did his work really accurately and managed to identify all
>>>>>> exceptions thrown by the methods he calls in one version of Apache
>>>>>> Commons Math. When we change an error detection and decide that a method
>>>>>> that did throw only MaxCountExceededException a method should throw
>>>>>> NumberIsToolLargeException instead (or in addition to the existing one),
>>>>>> then the calling code would still compile, but the new exception would
>>>>>> now go all the way upward. The two exceptions have no common ancestor
>>>>>> that can be catched, except Exception itself. With a single rooted
>>>>>> hierarchy, users can use some defensive programming: they can catch the
>>>>>> common root and be safe when we change some internal details.
>>>>>>
>>>>>> A single root would also bring two things I find useful.
>>>>>>
>>>>>> The first useful thing is that the ExceptionContextProvider could be
>>>>>> implemented at the root level, so we could retrieve this context (in
>>>>>> fact, I sometime needs even to retrive the pattern and the arguments
>>>>>> from the context, and we also miss getters for that, but they are easy
>>>>>> to add). It is not possible to catch ExceptionContextProvider because it
>>>>>> is not a throwable (Throwable is a class, not an interface, so we
>>>>>> inherit the Throwable nature from the top level class, not as
>>>>>> implementing the ExceptionContextProvider interface.
>>>>>>
>>>>>> The second useful thing is for [math] development itself. With a single
>>>>>> root, we can temporarily change its parent class from RuntimeException
>>>>>> to Exception, then fix all missing throws declaration and javadoc, then
>>>>>> put the parent class back before committing. This would help having more
>>>>>> up to date declarations. For now, I am sure we have missed a lot of our
>>>>>> own exceptions and let them propagate upward without anybody knowing it.
>>>> "let them propagate upward without anybody knowing it"
>>>> What do you mean? [Of course, all CM exceptions propagate upwards; that's
>>>> the purpose of raising them in the first place.]
>>>> Or did you just mean that the documentation is missing?
>>> I meant the documentation is missing.
>>>
>>>>>> As a test, I have just changed the parent for
>>>>>> MathIllegalArgumentException to Exception. I got 1384 compilation
>>>>>> errors. Just going to the first one (a constructor of
>>>>>> BaseAbstractUnivariateIntegrator), I saw we did not advertise the fact
>>>>>> it may throw NumberIsTooSmallException and NotStrictlyPositiveException,
>>>>>> neither in a throws declaration nor in the javadoc. I did not look at
>>>>>> the 1383 other errors...
>>>>> This is a good point.
>>>>>>> What I am missing is how knowing that an
>>>>>>> aspecific RTE came from within [math] makes a difference.  I am
>>>>>>> skeptical about ever depending on that kind of conclusion because
>>>>>>> dependencies may bring [math] code in at multiple levels.  Also, is
>>>>>>> there an implied assumption in your ideal setup that *no* exceptions
>>>>>>> propagate to [math] clients other than MRTE (i.e. we catch and wrap
>>>>>>> everything)?
>>>>>> No, I don't make this assumption. I consider that at upper levels, code
>>>>>> can receive exception from all layers underneath ([math] at the very
>>>>>> bottom, but also other layers in between). With two or three layers, you
>>>>>> can still handle a few library-wide exceptions (see my example with
>>>>>> MathRuntimeException, and MylibException above). However, if at one
>>>>>> level the development rules state that all exception must be caught and
>>>>>> wrapped (this happens in some critical systems contexts), then a single
>>>>>> root hierarchy helps a lot.
>>>>> But if we allow some exceptions to propagate unwrapped, this does
>>>>> not work, unless I am missing the point here.
>>>> AIUI, when a CM exception is thrown, one (obviously) knows that CM threw it.
>>>> When another exception (not a subclass of "MathRuntimeException") is thrown,
>>>> it did not come from a "throw" statement written in a CM source file.
>>> Right.
>>>
>>>>>> My point is that with a single root, we can get the best of two worlds:
>>>>>> large scope catches and pinpointed catches. The choice remains open for
>>>>>> users. With a multi-rooted hierarchy, we force users to duplicate the
>>>>>> same work for all exceptions we may throw, and we also force them to
>>>>>> recheck everything when we publish a new version, even despite we
>>>>>> ourselves fail to document these exceptions accurately.
>>>>> We need to fix the documentation.  If going back to a single root
>>>>> makes automatic detection of gaps possible, that by itself is almost
>>>>> enough to get me to agree to go back to the single root.  Your
>>>>> arguments above (which I honestly only partially follow) are enough
>>>>> to make me +0 for this change.  I think I probably put too much
>>>>> weight on favoring standard exceptions when we are really only
>>>>> talking about "reinventing" a handful of them.
>>>> I think that there is no relationship between single root hierarchy and
>>>> fixing the documentation...
>>>> [Unless we mean to indiscriminately indicate
>>>> ---
>>>>   @throws MathRuntimeException if something goes wrong.
>>>> ---
>>>> everywhere.]
>>> Single root simplifies this. We hage to apply the trick only once.
>>>
>> I think we had a discussion a few months ago on how exceptions should
>> be documented. We came to no agreement at that time, although one
>> option (which I followed) was to
>>   - remove unchecked exceptions from the method's signature
>>   - add the unchecjked exceptions to the javadoc.
>> I agree we should make sure that all exceptions are advertised in the
>> javadoc. However, I don't see how Luc's trick can help us in this case
>> (if we agree that exceptions should *not* appear in the signature). Am
>> I missing something?
> No, you are not missing anything. Having only the javadoc without the
> declaration in the signature is a pain. I would prefer to keep both. 

+1

Just "going boom" with an unadvertised RTE is not acceptable
behavior.  We used to be very good about documenting and advertising
all exceptions generated by [math].  I would very much like to see
us get back to that level of API quality.  The fact that we can use
Luc's trick to verify that we have not missed anything is enough to
make me +1 for going back to a single root.

Phil


> As
> I said earlier in this thread, I gave up on the discussion at some time
> and did not participate to the last occurrence you point out. I thought
> I served a lost cause then.
>
> Luc
>
>
>> Sébastien
>>
>>
>> ---------------------------------------------------------------------
>> 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
>
>


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

Re: [math] Re: Single root for Exceptions

[Luc Maisonobe <Lu...@free.fr>]

Le 29/08/2012 20:31, Sébastien Brisard a écrit :
> Hello,

Hi Sébastien,

> 
> 2012/8/29 Luc Maisonobe <Lu...@free.fr>:
>> Le 29/08/2012 01:40, Gilles Sadowski a écrit :
>>> Hi.
>>
>> Hello,
>>
>>>
>>>>> [...]
>>>>
>>>> I think I get your point, but again given transitive / nested
>>>> dependencies I would not want to depend on it, even if all of the
>>>> components have single-rooted exception hierarchies.  This is
>>>> especially true if not all components adhere to the "wrap
>>>> everything" rule - i.e., if they can generate and/or propagate RTEs
>>>> that do not inherit from their base exception class.  From the
>>>> standpoint of the caller, for example, what is the difference
>>>> between [math]
>>>>
>>>> 0)  throwing IAE
>>>> 1)  throwing MathIAE derived from IAE
>>>> 2)  throwing MathIAE derived from MathRTE (base)
>>>> assuming that [math] is not signing up to wrap and rethrow every
>>>> exception - including IAE - we get from JDK classes?  Will the
>>
>> I was talking only about what we do throw ourselves.
>>
>>>> caller actually do anything different if the RTE is math-wrapped vs
>>>> "naked" but coming out of the [math] code?  I understand that the
>>>> try/catch may be several layers removed from the code calling a
>>>> [math] API.
>>>>
>>>> Same applies to NPE, which we don't subclass now, but mostly handle
>>>> as IAE.
>>>>
>>>> I guess one thing we might consider is trying to design for the
>>>> invariant that we never propagate RTEs without wrapping.  But that
>>>> would be a lot of work to retrofit and would have a performance cost.
>>>
>>> I don't think that Luc means that we must wrap everyting in a home-made
>>> exception.
>>
>> Gilles is right, I did not intend to catch and wrap everything.
>>
>>>
>>> Two possible cases for NPE:
>>>  * The caller passed a "null" reference and will get, sooner or later, an
>>>    NPE: it's a bug in his application.
>>>  * An NPE was raised by a bug in CM, and we must fix it.
>>>
>>> I think that we should not check for "null" and thus have no use for an NPE
>>> wrapper.
>>
>> I agree. We shouldn' wrap this.
>>
>>>
>>> Are there other "naked" exceptions that could come out of CM?
>>> The policy of extensive precondition checking has the purpose (I think) to
>>> prevent unexpected ("naked" or not) exceptions. If some slip through
>>> nevertheless, doesn't it mean that we miss some check?
>>
>> I think we catch what we need to catch and already have a ggod deal of
>> checking. Of course, we surely missed a few cases, we will fix them when
>> they are identified.
>>
>>>
>>>>
>>>>> Another problem is maintenance. Even if you consider the intermediate
>>>>> developer did his work really accurately and managed to identify all
>>>>> exceptions thrown by the methods he calls in one version of Apache
>>>>> Commons Math. When we change an error detection and decide that a method
>>>>> that did throw only MaxCountExceededException a method should throw
>>>>> NumberIsToolLargeException instead (or in addition to the existing one),
>>>>> then the calling code would still compile, but the new exception would
>>>>> now go all the way upward. The two exceptions have no common ancestor
>>>>> that can be catched, except Exception itself. With a single rooted
>>>>> hierarchy, users can use some defensive programming: they can catch the
>>>>> common root and be safe when we change some internal details.
>>>>>
>>>>> A single root would also bring two things I find useful.
>>>>>
>>>>> The first useful thing is that the ExceptionContextProvider could be
>>>>> implemented at the root level, so we could retrieve this context (in
>>>>> fact, I sometime needs even to retrive the pattern and the arguments
>>>>> from the context, and we also miss getters for that, but they are easy
>>>>> to add). It is not possible to catch ExceptionContextProvider because it
>>>>> is not a throwable (Throwable is a class, not an interface, so we
>>>>> inherit the Throwable nature from the top level class, not as
>>>>> implementing the ExceptionContextProvider interface.
>>>>>
>>>>> The second useful thing is for [math] development itself. With a single
>>>>> root, we can temporarily change its parent class from RuntimeException
>>>>> to Exception, then fix all missing throws declaration and javadoc, then
>>>>> put the parent class back before committing. This would help having more
>>>>> up to date declarations. For now, I am sure we have missed a lot of our
>>>>> own exceptions and let them propagate upward without anybody knowing it.
>>>
>>> "let them propagate upward without anybody knowing it"
>>> What do you mean? [Of course, all CM exceptions propagate upwards; that's
>>> the purpose of raising them in the first place.]
>>> Or did you just mean that the documentation is missing?
>>
>> I meant the documentation is missing.
>>
>>>
>>>>> As a test, I have just changed the parent for
>>>>> MathIllegalArgumentException to Exception. I got 1384 compilation
>>>>> errors. Just going to the first one (a constructor of
>>>>> BaseAbstractUnivariateIntegrator), I saw we did not advertise the fact
>>>>> it may throw NumberIsTooSmallException and NotStrictlyPositiveException,
>>>>> neither in a throws declaration nor in the javadoc. I did not look at
>>>>> the 1383 other errors...
>>>>
>>>> This is a good point.
>>>>>
>>>>>> What I am missing is how knowing that an
>>>>>> aspecific RTE came from within [math] makes a difference.  I am
>>>>>> skeptical about ever depending on that kind of conclusion because
>>>>>> dependencies may bring [math] code in at multiple levels.  Also, is
>>>>>> there an implied assumption in your ideal setup that *no* exceptions
>>>>>> propagate to [math] clients other than MRTE (i.e. we catch and wrap
>>>>>> everything)?
>>>>> No, I don't make this assumption. I consider that at upper levels, code
>>>>> can receive exception from all layers underneath ([math] at the very
>>>>> bottom, but also other layers in between). With two or three layers, you
>>>>> can still handle a few library-wide exceptions (see my example with
>>>>> MathRuntimeException, and MylibException above). However, if at one
>>>>> level the development rules state that all exception must be caught and
>>>>> wrapped (this happens in some critical systems contexts), then a single
>>>>> root hierarchy helps a lot.
>>>>
>>>> But if we allow some exceptions to propagate unwrapped, this does
>>>> not work, unless I am missing the point here.
>>>
>>> AIUI, when a CM exception is thrown, one (obviously) knows that CM threw it.
>>> When another exception (not a subclass of "MathRuntimeException") is thrown,
>>> it did not come from a "throw" statement written in a CM source file.
>>
>> Right.
>>
>>>
>>>>>
>>>>> My point is that with a single root, we can get the best of two worlds:
>>>>> large scope catches and pinpointed catches. The choice remains open for
>>>>> users. With a multi-rooted hierarchy, we force users to duplicate the
>>>>> same work for all exceptions we may throw, and we also force them to
>>>>> recheck everything when we publish a new version, even despite we
>>>>> ourselves fail to document these exceptions accurately.
>>>>
>>>> We need to fix the documentation.  If going back to a single root
>>>> makes automatic detection of gaps possible, that by itself is almost
>>>> enough to get me to agree to go back to the single root.  Your
>>>> arguments above (which I honestly only partially follow) are enough
>>>> to make me +0 for this change.  I think I probably put too much
>>>> weight on favoring standard exceptions when we are really only
>>>> talking about "reinventing" a handful of them.
>>>
>>> I think that there is no relationship between single root hierarchy and
>>> fixing the documentation...
>>> [Unless we mean to indiscriminately indicate
>>> ---
>>>   @throws MathRuntimeException if something goes wrong.
>>> ---
>>> everywhere.]
>>
>> Single root simplifies this. We hage to apply the trick only once.
>>
> I think we had a discussion a few months ago on how exceptions should
> be documented. We came to no agreement at that time, although one
> option (which I followed) was to
>   - remove unchecked exceptions from the method's signature
>   - add the unchecjked exceptions to the javadoc.
> I agree we should make sure that all exceptions are advertised in the
> javadoc. However, I don't see how Luc's trick can help us in this case
> (if we agree that exceptions should *not* appear in the signature). Am
> I missing something?

No, you are not missing anything. Having only the javadoc without the
declaration in the signature is a pain. I would prefer to keep both. As
I said earlier in this thread, I gave up on the discussion at some time
and did not participate to the last occurrence you point out. I thought
I served a lost cause then.

Luc


> 
> Sébastien
> 
> 
> ---------------------------------------------------------------------
> 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

Re: [math] Re: Single root for Exceptions

[Sébastien Brisard <se...@m4x.org>]

Hello,

2012/8/29 Luc Maisonobe <Lu...@free.fr>:
> Le 29/08/2012 01:40, Gilles Sadowski a écrit :
>> Hi.
>
> Hello,
>
>>
>>>> [...]
>>>
>>> I think I get your point, but again given transitive / nested
>>> dependencies I would not want to depend on it, even if all of the
>>> components have single-rooted exception hierarchies.  This is
>>> especially true if not all components adhere to the "wrap
>>> everything" rule - i.e., if they can generate and/or propagate RTEs
>>> that do not inherit from their base exception class.  From the
>>> standpoint of the caller, for example, what is the difference
>>> between [math]
>>>
>>> 0)  throwing IAE
>>> 1)  throwing MathIAE derived from IAE
>>> 2)  throwing MathIAE derived from MathRTE (base)
>>> assuming that [math] is not signing up to wrap and rethrow every
>>> exception - including IAE - we get from JDK classes?  Will the
>
> I was talking only about what we do throw ourselves.
>
>>> caller actually do anything different if the RTE is math-wrapped vs
>>> "naked" but coming out of the [math] code?  I understand that the
>>> try/catch may be several layers removed from the code calling a
>>> [math] API.
>>>
>>> Same applies to NPE, which we don't subclass now, but mostly handle
>>> as IAE.
>>>
>>> I guess one thing we might consider is trying to design for the
>>> invariant that we never propagate RTEs without wrapping.  But that
>>> would be a lot of work to retrofit and would have a performance cost.
>>
>> I don't think that Luc means that we must wrap everyting in a home-made
>> exception.
>
> Gilles is right, I did not intend to catch and wrap everything.
>
>>
>> Two possible cases for NPE:
>>  * The caller passed a "null" reference and will get, sooner or later, an
>>    NPE: it's a bug in his application.
>>  * An NPE was raised by a bug in CM, and we must fix it.
>>
>> I think that we should not check for "null" and thus have no use for an NPE
>> wrapper.
>
> I agree. We shouldn' wrap this.
>
>>
>> Are there other "naked" exceptions that could come out of CM?
>> The policy of extensive precondition checking has the purpose (I think) to
>> prevent unexpected ("naked" or not) exceptions. If some slip through
>> nevertheless, doesn't it mean that we miss some check?
>
> I think we catch what we need to catch and already have a ggod deal of
> checking. Of course, we surely missed a few cases, we will fix them when
> they are identified.
>
>>
>>>
>>>> Another problem is maintenance. Even if you consider the intermediate
>>>> developer did his work really accurately and managed to identify all
>>>> exceptions thrown by the methods he calls in one version of Apache
>>>> Commons Math. When we change an error detection and decide that a method
>>>> that did throw only MaxCountExceededException a method should throw
>>>> NumberIsToolLargeException instead (or in addition to the existing one),
>>>> then the calling code would still compile, but the new exception would
>>>> now go all the way upward. The two exceptions have no common ancestor
>>>> that can be catched, except Exception itself. With a single rooted
>>>> hierarchy, users can use some defensive programming: they can catch the
>>>> common root and be safe when we change some internal details.
>>>>
>>>> A single root would also bring two things I find useful.
>>>>
>>>> The first useful thing is that the ExceptionContextProvider could be
>>>> implemented at the root level, so we could retrieve this context (in
>>>> fact, I sometime needs even to retrive the pattern and the arguments
>>>> from the context, and we also miss getters for that, but they are easy
>>>> to add). It is not possible to catch ExceptionContextProvider because it
>>>> is not a throwable (Throwable is a class, not an interface, so we
>>>> inherit the Throwable nature from the top level class, not as
>>>> implementing the ExceptionContextProvider interface.
>>>>
>>>> The second useful thing is for [math] development itself. With a single
>>>> root, we can temporarily change its parent class from RuntimeException
>>>> to Exception, then fix all missing throws declaration and javadoc, then
>>>> put the parent class back before committing. This would help having more
>>>> up to date declarations. For now, I am sure we have missed a lot of our
>>>> own exceptions and let them propagate upward without anybody knowing it.
>>
>> "let them propagate upward without anybody knowing it"
>> What do you mean? [Of course, all CM exceptions propagate upwards; that's
>> the purpose of raising them in the first place.]
>> Or did you just mean that the documentation is missing?
>
> I meant the documentation is missing.
>
>>
>>>> As a test, I have just changed the parent for
>>>> MathIllegalArgumentException to Exception. I got 1384 compilation
>>>> errors. Just going to the first one (a constructor of
>>>> BaseAbstractUnivariateIntegrator), I saw we did not advertise the fact
>>>> it may throw NumberIsTooSmallException and NotStrictlyPositiveException,
>>>> neither in a throws declaration nor in the javadoc. I did not look at
>>>> the 1383 other errors...
>>>
>>> This is a good point.
>>>>
>>>>> What I am missing is how knowing that an
>>>>> aspecific RTE came from within [math] makes a difference.  I am
>>>>> skeptical about ever depending on that kind of conclusion because
>>>>> dependencies may bring [math] code in at multiple levels.  Also, is
>>>>> there an implied assumption in your ideal setup that *no* exceptions
>>>>> propagate to [math] clients other than MRTE (i.e. we catch and wrap
>>>>> everything)?
>>>> No, I don't make this assumption. I consider that at upper levels, code
>>>> can receive exception from all layers underneath ([math] at the very
>>>> bottom, but also other layers in between). With two or three layers, you
>>>> can still handle a few library-wide exceptions (see my example with
>>>> MathRuntimeException, and MylibException above). However, if at one
>>>> level the development rules state that all exception must be caught and
>>>> wrapped (this happens in some critical systems contexts), then a single
>>>> root hierarchy helps a lot.
>>>
>>> But if we allow some exceptions to propagate unwrapped, this does
>>> not work, unless I am missing the point here.
>>
>> AIUI, when a CM exception is thrown, one (obviously) knows that CM threw it.
>> When another exception (not a subclass of "MathRuntimeException") is thrown,
>> it did not come from a "throw" statement written in a CM source file.
>
> Right.
>
>>
>>>>
>>>> My point is that with a single root, we can get the best of two worlds:
>>>> large scope catches and pinpointed catches. The choice remains open for
>>>> users. With a multi-rooted hierarchy, we force users to duplicate the
>>>> same work for all exceptions we may throw, and we also force them to
>>>> recheck everything when we publish a new version, even despite we
>>>> ourselves fail to document these exceptions accurately.
>>>
>>> We need to fix the documentation.  If going back to a single root
>>> makes automatic detection of gaps possible, that by itself is almost
>>> enough to get me to agree to go back to the single root.  Your
>>> arguments above (which I honestly only partially follow) are enough
>>> to make me +0 for this change.  I think I probably put too much
>>> weight on favoring standard exceptions when we are really only
>>> talking about "reinventing" a handful of them.
>>
>> I think that there is no relationship between single root hierarchy and
>> fixing the documentation...
>> [Unless we mean to indiscriminately indicate
>> ---
>>   @throws MathRuntimeException if something goes wrong.
>> ---
>> everywhere.]
>
> Single root simplifies this. We hage to apply the trick only once.
>
I think we had a discussion a few months ago on how exceptions should
be documented. We came to no agreement at that time, although one
option (which I followed) was to
  - remove unchecked exceptions from the method's signature
  - add the unchecjked exceptions to the javadoc.
I agree we should make sure that all exceptions are advertised in the
javadoc. However, I don't see how Luc's trick can help us in this case
(if we agree that exceptions should *not* appear in the signature). Am
I missing something?

Sébastien


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

[math] Re: Single root for Exceptions

[Luc Maisonobe <Lu...@free.fr>]

Le 29/08/2012 01:40, Gilles Sadowski a écrit :
> Hi.

Hello,

> 
>>> [...]
>>
>> I think I get your point, but again given transitive / nested
>> dependencies I would not want to depend on it, even if all of the
>> components have single-rooted exception hierarchies.  This is
>> especially true if not all components adhere to the "wrap
>> everything" rule - i.e., if they can generate and/or propagate RTEs
>> that do not inherit from their base exception class.  From the
>> standpoint of the caller, for example, what is the difference
>> between [math]
>>
>> 0)  throwing IAE
>> 1)  throwing MathIAE derived from IAE
>> 2)  throwing MathIAE derived from MathRTE (base)
>> assuming that [math] is not signing up to wrap and rethrow every
>> exception - including IAE - we get from JDK classes?  Will the

I was talking only about what we do throw ourselves.

>> caller actually do anything different if the RTE is math-wrapped vs
>> "naked" but coming out of the [math] code?  I understand that the
>> try/catch may be several layers removed from the code calling a
>> [math] API. 
>>
>> Same applies to NPE, which we don't subclass now, but mostly handle
>> as IAE.
>>
>> I guess one thing we might consider is trying to design for the
>> invariant that we never propagate RTEs without wrapping.  But that
>> would be a lot of work to retrofit and would have a performance cost.
> 
> I don't think that Luc means that we must wrap everyting in a home-made
> exception.

Gilles is right, I did not intend to catch and wrap everything.

> 
> Two possible cases for NPE:
>  * The caller passed a "null" reference and will get, sooner or later, an
>    NPE: it's a bug in his application.
>  * An NPE was raised by a bug in CM, and we must fix it.
> 
> I think that we should not check for "null" and thus have no use for an NPE
> wrapper.

I agree. We shouldn' wrap this.

> 
> Are there other "naked" exceptions that could come out of CM?
> The policy of extensive precondition checking has the purpose (I think) to
> prevent unexpected ("naked" or not) exceptions. If some slip through
> nevertheless, doesn't it mean that we miss some check?

I think we catch what we need to catch and already have a ggod deal of
checking. Of course, we surely missed a few cases, we will fix them when
they are identified.

> 
>>
>>> Another problem is maintenance. Even if you consider the intermediate
>>> developer did his work really accurately and managed to identify all
>>> exceptions thrown by the methods he calls in one version of Apache
>>> Commons Math. When we change an error detection and decide that a method
>>> that did throw only MaxCountExceededException a method should throw
>>> NumberIsToolLargeException instead (or in addition to the existing one),
>>> then the calling code would still compile, but the new exception would
>>> now go all the way upward. The two exceptions have no common ancestor
>>> that can be catched, except Exception itself. With a single rooted
>>> hierarchy, users can use some defensive programming: they can catch the
>>> common root and be safe when we change some internal details.
>>>
>>> A single root would also bring two things I find useful.
>>>
>>> The first useful thing is that the ExceptionContextProvider could be
>>> implemented at the root level, so we could retrieve this context (in
>>> fact, I sometime needs even to retrive the pattern and the arguments
>>> from the context, and we also miss getters for that, but they are easy
>>> to add). It is not possible to catch ExceptionContextProvider because it
>>> is not a throwable (Throwable is a class, not an interface, so we
>>> inherit the Throwable nature from the top level class, not as
>>> implementing the ExceptionContextProvider interface.
>>>
>>> The second useful thing is for [math] development itself. With a single
>>> root, we can temporarily change its parent class from RuntimeException
>>> to Exception, then fix all missing throws declaration and javadoc, then
>>> put the parent class back before committing. This would help having more
>>> up to date declarations. For now, I am sure we have missed a lot of our
>>> own exceptions and let them propagate upward without anybody knowing it.
> 
> "let them propagate upward without anybody knowing it"
> What do you mean? [Of course, all CM exceptions propagate upwards; that's
> the purpose of raising them in the first place.]
> Or did you just mean that the documentation is missing?

I meant the documentation is missing.

> 
>>> As a test, I have just changed the parent for
>>> MathIllegalArgumentException to Exception. I got 1384 compilation
>>> errors. Just going to the first one (a constructor of
>>> BaseAbstractUnivariateIntegrator), I saw we did not advertise the fact
>>> it may throw NumberIsTooSmallException and NotStrictlyPositiveException,
>>> neither in a throws declaration nor in the javadoc. I did not look at
>>> the 1383 other errors...
>>
>> This is a good point.
>>>
>>>> What I am missing is how knowing that an
>>>> aspecific RTE came from within [math] makes a difference.  I am
>>>> skeptical about ever depending on that kind of conclusion because
>>>> dependencies may bring [math] code in at multiple levels.  Also, is
>>>> there an implied assumption in your ideal setup that *no* exceptions
>>>> propagate to [math] clients other than MRTE (i.e. we catch and wrap
>>>> everything)?
>>> No, I don't make this assumption. I consider that at upper levels, code
>>> can receive exception from all layers underneath ([math] at the very
>>> bottom, but also other layers in between). With two or three layers, you
>>> can still handle a few library-wide exceptions (see my example with
>>> MathRuntimeException, and MylibException above). However, if at one
>>> level the development rules state that all exception must be caught and
>>> wrapped (this happens in some critical systems contexts), then a single
>>> root hierarchy helps a lot.
>>
>> But if we allow some exceptions to propagate unwrapped, this does
>> not work, unless I am missing the point here.
> 
> AIUI, when a CM exception is thrown, one (obviously) knows that CM threw it.
> When another exception (not a subclass of "MathRuntimeException") is thrown,
> it did not come from a "throw" statement written in a CM source file.

Right.

> 
>>>
>>> My point is that with a single root, we can get the best of two worlds:
>>> large scope catches and pinpointed catches. The choice remains open for
>>> users. With a multi-rooted hierarchy, we force users to duplicate the
>>> same work for all exceptions we may throw, and we also force them to
>>> recheck everything when we publish a new version, even despite we
>>> ourselves fail to document these exceptions accurately.
>>
>> We need to fix the documentation.  If going back to a single root
>> makes automatic detection of gaps possible, that by itself is almost
>> enough to get me to agree to go back to the single root.  Your
>> arguments above (which I honestly only partially follow) are enough
>> to make me +0 for this change.  I think I probably put too much
>> weight on favoring standard exceptions when we are really only
>> talking about "reinventing" a handful of them.
> 
> I think that there is no relationship between single root hierarchy and
> fixing the documentation...
> [Unless we mean to indiscriminately indicate
> ---
>   @throws MathRuntimeException if something goes wrong.
> ---
> everywhere.]

Single root simplifies this. We hage to apply the trick only once.

Luc

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

Re: Single root for Exceptions

[Gilles Sadowski <gi...@harfang.homelinux.org>]

Hi.

> > [...]
> 
> I think I get your point, but again given transitive / nested
> dependencies I would not want to depend on it, even if all of the
> components have single-rooted exception hierarchies.  This is
> especially true if not all components adhere to the "wrap
> everything" rule - i.e., if they can generate and/or propagate RTEs
> that do not inherit from their base exception class.  From the
> standpoint of the caller, for example, what is the difference
> between [math]
> 
> 0)  throwing IAE
> 1)  throwing MathIAE derived from IAE
> 2)  throwing MathIAE derived from MathRTE (base)
> assuming that [math] is not signing up to wrap and rethrow every
> exception - including IAE - we get from JDK classes?  Will the
> caller actually do anything different if the RTE is math-wrapped vs
> "naked" but coming out of the [math] code?  I understand that the
> try/catch may be several layers removed from the code calling a
> [math] API. 
> 
> Same applies to NPE, which we don't subclass now, but mostly handle
> as IAE.
> 
> I guess one thing we might consider is trying to design for the
> invariant that we never propagate RTEs without wrapping.  But that
> would be a lot of work to retrofit and would have a performance cost.

I don't think that Luc means that we must wrap everyting in a home-made
exception.

Two possible cases for NPE:
 * The caller passed a "null" reference and will get, sooner or later, an
   NPE: it's a bug in his application.
 * An NPE was raised by a bug in CM, and we must fix it.

I think that we should not check for "null" and thus have no use for an NPE
wrapper.

Are there other "naked" exceptions that could come out of CM?
The policy of extensive precondition checking has the purpose (I think) to
prevent unexpected ("naked" or not) exceptions. If some slip through
nevertheless, doesn't it mean that we miss some check?

> 
> > Another problem is maintenance. Even if you consider the intermediate
> > developer did his work really accurately and managed to identify all
> > exceptions thrown by the methods he calls in one version of Apache
> > Commons Math. When we change an error detection and decide that a method
> > that did throw only MaxCountExceededException a method should throw
> > NumberIsToolLargeException instead (or in addition to the existing one),
> > then the calling code would still compile, but the new exception would
> > now go all the way upward. The two exceptions have no common ancestor
> > that can be catched, except Exception itself. With a single rooted
> > hierarchy, users can use some defensive programming: they can catch the
> > common root and be safe when we change some internal details.
> >
> > A single root would also bring two things I find useful.
> >
> > The first useful thing is that the ExceptionContextProvider could be
> > implemented at the root level, so we could retrieve this context (in
> > fact, I sometime needs even to retrive the pattern and the arguments
> > from the context, and we also miss getters for that, but they are easy
> > to add). It is not possible to catch ExceptionContextProvider because it
> > is not a throwable (Throwable is a class, not an interface, so we
> > inherit the Throwable nature from the top level class, not as
> > implementing the ExceptionContextProvider interface.
> >
> > The second useful thing is for [math] development itself. With a single
> > root, we can temporarily change its parent class from RuntimeException
> > to Exception, then fix all missing throws declaration and javadoc, then
> > put the parent class back before committing. This would help having more
> > up to date declarations. For now, I am sure we have missed a lot of our
> > own exceptions and let them propagate upward without anybody knowing it.

"let them propagate upward without anybody knowing it"
What do you mean? [Of course, all CM exceptions propagate upwards; that's
the purpose of raising them in the first place.]
Or did you just mean that the documentation is missing?

> > As a test, I have just changed the parent for
> > MathIllegalArgumentException to Exception. I got 1384 compilation
> > errors. Just going to the first one (a constructor of
> > BaseAbstractUnivariateIntegrator), I saw we did not advertise the fact
> > it may throw NumberIsTooSmallException and NotStrictlyPositiveException,
> > neither in a throws declaration nor in the javadoc. I did not look at
> > the 1383 other errors...
> 
> This is a good point.
> >
> >> What I am missing is how knowing that an
> >> aspecific RTE came from within [math] makes a difference.  I am
> >> skeptical about ever depending on that kind of conclusion because
> >> dependencies may bring [math] code in at multiple levels.  Also, is
> >> there an implied assumption in your ideal setup that *no* exceptions
> >> propagate to [math] clients other than MRTE (i.e. we catch and wrap
> >> everything)?
> > No, I don't make this assumption. I consider that at upper levels, code
> > can receive exception from all layers underneath ([math] at the very
> > bottom, but also other layers in between). With two or three layers, you
> > can still handle a few library-wide exceptions (see my example with
> > MathRuntimeException, and MylibException above). However, if at one
> > level the development rules state that all exception must be caught and
> > wrapped (this happens in some critical systems contexts), then a single
> > root hierarchy helps a lot.
> 
> But if we allow some exceptions to propagate unwrapped, this does
> not work, unless I am missing the point here.

AIUI, when a CM exception is thrown, one (obviously) knows that CM threw it.
When another exception (not a subclass of "MathRuntimeException") is thrown,
it did not come from a "throw" statement written in a CM source file.

> >
> > My point is that with a single root, we can get the best of two worlds:
> > large scope catches and pinpointed catches. The choice remains open for
> > users. With a multi-rooted hierarchy, we force users to duplicate the
> > same work for all exceptions we may throw, and we also force them to
> > recheck everything when we publish a new version, even despite we
> > ourselves fail to document these exceptions accurately.
> 
> We need to fix the documentation.  If going back to a single root
> makes automatic detection of gaps possible, that by itself is almost
> enough to get me to agree to go back to the single root.  Your
> arguments above (which I honestly only partially follow) are enough
> to make me +0 for this change.  I think I probably put too much
> weight on favoring standard exceptions when we are really only
> talking about "reinventing" a handful of them.

I think that there is no relationship between single root hierarchy and
fixing the documentation...
[Unless we mean to indiscriminately indicate
---
  @throws MathRuntimeException if something goes wrong.
---
everywhere.]


Gilles

> [...]

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