[math] using the ExceptionContext facility

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

Hi,
in the discussions regarding MATH-581, appeared the question of how to
use o.a.c.m.exception.util.ExceptionContext properly. Context is nice,
since it provides the method throwing the exception a very flexible
way to send some additional information on what actually happened, and
which object(s) caused the exception. Their use is very simple : an
Object is associated to a String key.
One of the issues we faced is the choice of the actual key names.
Ideally, a consistent naming convention should be adopted. Some of the
questions are
* how do you capitalize the string ?
* should verbose or short names be used ?
* how are the key names to be stored ? As public constants within the
classe implementing the method which throws the exception, or in a big
enum, just like exception messages?

At this point, I'm not even sure about the questions this issue
raises, so any comment would be most welcome !

Best,
Sebastien

PS : Maybe an example would be in order here. Preconditioned conjugate
gradient requires that both the linear operator of the system, a, and
the preconditioner, m, be positive definite. During the CG iterations,
a NonPositiveDefiniteLinearOperator is thrown if one vector x is
found, such that x'.a.x <= 0 or x'.m.x <= 0.
At the moment, what I do is the following.

CASE 1 : during the iterations, r is found, such as r'.m.r <= 0
--- CUT ---
                final NonPositiveDefiniteLinearOperatorException e;
                e = new NonPositiveDefiniteLinearOperatorException();
                final ExceptionContext context = e.getContext();
                context.setValue(OPERATOR, m);
                context.setValue(VECTOR, r);
                throw e;
---CUT---

CASE 2 : during the iterations, p is found, such as p'.a.p <= 0
---CUT---
                final NonPositiveDefiniteLinearOperatorException e;
                e = new NonPositiveDefiniteLinearOperatorException();
                final ExceptionContext context = e.getContext();
                context.setValue(OPERATOR, a);
                context.setValue(VECTOR, p);
                throw e;
---CUT---

Where OPERATOR and VECTOR are two String constants, defined in the
ConjugateGradient class
    public static final String OPERATOR = "operator";
    public static final String VECTOR = "vector";
the constants are public, so that a user can invoke them in order to
retrieve the corresponding offending object.

The javadoc specifies which keys are bound to which offending objects,
in the case an exception is thrown.

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