You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by Sébastien Brisard <se...@m4x.org> on 2011/08/26 05:47:30 UTC
[math] Consistent use of ExceptionContext [was "using the
ExceptionContext facility"]
Hi,
a while ago, I started a thread on the "proper" of keys in
ExceptionContext. This message was too vague, and raised very (very)
little interest. Hope this one will be more successful... I now have a
suggestion, which would work in at least some cases.
Very briefly, the issue is the following: the key names are attributed
by the method which throws the exception (say iThrowTheException()).
Now, the problem is: how does the method which catches the exception
(say iCatchTheException()) make sense out of this key name? The answer
would be to document the key names in the javadoc of
iThrowTheException(). While very flexible this approach does not
guarantee a minimum level of consistency.
In some cases though, the potential context of a specific exception is
known beforehand. For example, in
o.a.c.m.linear.NonPositiveDefiniteLinearOperator, the context might be
the so-called offending operator and offending vector. Then, I propose
that key names be stored as public final static String and documented
*in the exception definition*. For example, in
NonPositiveDefiniteLinearOperator, we would have two constants
public final static String OPERATOR = "operator"
public final static String VECTOR = "vector"
Thanks for your comments!
Sébastien
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] Consistent use of ExceptionContext [was "using the
ExceptionContext facility"]
Posted by Gilles Sadowski <gi...@harfang.homelinux.org>.
Hello.
>
> 2011/8/26 Sébastien Brisard <se...@m4x.org>
>
> >
> > In other words, having this kind of context with documented keys would
> > help the end-user debug his own code. I hope I'm making my point
> > clearly, there.
> >
>
> More info attached to exceptions is great. I often find that the first half
> of fixing a bug is adding more explicit exception throw/catch handling and
> ever-more explicit messages, chasing the fault back to a root cause.
> However, you have to ask who is going to be making use of the exception. Is
> it someone who is debugging the library, or some user who's called into it
> and somehow got broken behaviour?
>
> For debugging, you are familiar with your own library, and can capture info
> about the state around where the exception was raised using your IDE in
> debug mode. Your users aren't familiar with the library, and should be able
> to tell from the exception message if it is most likely their fault (and if
> so, how to fix it), or the library's (in which case they may send you the
> stack-trace and we all know that better annotated exceptions make it easier
> to interpret these even across different builds).
>
> So, personally I would lean on the side of as much explicit info in the
> message as possible. "It was parameter A that borked me because it was XXX
> and I was expecting YYY". Don't rely upon line numbers, because these change
> as ppl edit the file and your users can understand 'A is borked' but can't
> understand a line number.
That's what is usually done when raising an exception: an explicit message
contains the direct cause of the failure.
What we discuss is how to propagate information that sometimes does not fit
into a string message.
> I wouldn't usually bother putting objects
> capturing state describing the faulty environment into the exception as I
> can get that from the debugger, given a test case. In my experience, a good
> proportion of the real causes of exceptions aren't co-located with where the
> exception is raised. Perhaps with the right cascades of exception handlers,
> all of which capture their relevant local state, you can then serialize the
> result out and have a pre-canned test-case for the failure. I'm not sure how
> practical this would be in the real world - I expect you'd drown in
> try/catch eventualities. You may be better logging the hinkey state very
> close to where the exception is raised rather than storing references to it.
In the case under consideration, logging the state is not an option, I
think, because the default string representation of the operator might not
be interesting and/or the full state might be too large.
Thus the "manual" extraction which a knowledgeable user will control to
save the state to an appropriate output.
[Moreover, there is no logging in CM...]
>
> Happy to be proved wrong though. Perhaps this is the beginning of an era of
> code that spits out bug unit tests when ever there are exceptions.
At least, with the exception context, you can have access to the cause of
the failure, and make a test out of it.
Regards,
Gilles
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] Consistent use of ExceptionContext [was "using the
ExceptionContext facility"]
Posted by Matthew Pocock <tu...@gmail.com>.
Hi,
2011/8/26 Sébastien Brisard <se...@m4x.org>
>
> In other words, having this kind of context with documented keys would
> help the end-user debug his own code. I hope I'm making my point
> clearly, there.
>
More info attached to exceptions is great. I often find that the first half
of fixing a bug is adding more explicit exception throw/catch handling and
ever-more explicit messages, chasing the fault back to a root cause.
However, you have to ask who is going to be making use of the exception. Is
it someone who is debugging the library, or some user who's called into it
and somehow got broken behaviour?
For debugging, you are familiar with your own library, and can capture info
about the state around where the exception was raised using your IDE in
debug mode. Your users aren't familiar with the library, and should be able
to tell from the exception message if it is most likely their fault (and if
so, how to fix it), or the library's (in which case they may send you the
stack-trace and we all know that better annotated exceptions make it easier
to interpret these even across different builds).
So, personally I would lean on the side of as much explicit info in the
message as possible. "It was parameter A that borked me because it was XXX
and I was expecting YYY". Don't rely upon line numbers, because these change
as ppl edit the file and your users can understand 'A is borked' but can't
understand a line number. I wouldn't usually bother putting objects
capturing state describing the faulty environment into the exception as I
can get that from the debugger, given a test case. In my experience, a good
proportion of the real causes of exceptions aren't co-located with where the
exception is raised. Perhaps with the right cascades of exception handlers,
all of which capture their relevant local state, you can then serialize the
result out and have a pre-canned test-case for the failure. I'm not sure how
practical this would be in the real world - I expect you'd drown in
try/catch eventualities. You may be better logging the hinkey state very
close to where the exception is raised rather than storing references to it.
Happy to be proved wrong though. Perhaps this is the beginning of an era of
code that spits out bug unit tests when ever there are exceptions.
Matthew
> Best regards,
> Sébastien
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>
--
Dr Matthew Pocock
Visitor, School of Computing Science, Newcastle University
mailto: turingatemyhamster@gmail.com
gchat: turingatemyhamster@gmail.com
msn: matthew_pocock@yahoo.co.uk
irc.freenode.net: drdozer
tel: (0191) 2566550
mob: +447535664143
Re: [math] Consistent use of ExceptionContext [was "using the
ExceptionContext facility"]
Posted by Sébastien Brisard <se...@m4x.org>.
>
> Do you mean that the context info for a (hyptohetical) method like
> doSomething(LinearOperator a, LinearOperator b)
> would be like
> offending operator: a
> or
> offending operator: b
> ?
>
> If so, is it not enough to just throw the exception? Won't it be obvious
> which operator is "offending" by looking at the line number in the stack
> trace?
>
In your example, the answer is definitely yes. And from this point of
view, using context is probably a very flexible solution, because we
would provide some context only where it would really be needed :
sometimes, a reference to the offending operator would certainly be
useless. Thus, in your example, if the exception is some sort of
DimensionMismatchException, I do not really need to know more than : a
(or b) has wrong dimensions. Fix is easy.
But I can think of other cases where the answer is probably no. For
example, let us consider the Unpreconditioned Conjugate Gradient
method. In this case, if a NonPositiveDefiniteLinearOperator is
thrown, there is no ambiguity as to which operator is the cause (there
is only one operator). However, the context would also hold a
reference to the offending vector x, which could be invaluable.
Let's assume I have proved mathematically that a (huge) linear
operator a is positive definite. I go on implementing it, and pass it
to the CG method, which throws a NonPositiveDefiniteLinearOperator.
This means that during the iterations, the solver has found this rare
counter-example x which proves that my implementation is faulty (x is
such that x'.a.x <= 0). Just knowing that my implementation has a bug
is already quite good. But retrieving a *reference* to the offending
vector x would allow me to reproduce the bug *outside* the iterations
of the CG solver.
In other words, having this kind of context with documented keys would
help the end-user debug his own code. I hope I'm making my point
clearly, there.
Best regards,
Sébastien
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] Consistent use of ExceptionContext [was "using the
ExceptionContext facility"]
Posted by Gilles Sadowski <gi...@harfang.homelinux.org>.
Hi.
> > I am assuming that the main difference between using the "ExceptionContext"
> > and passing information in the exception's constructor is that in the
> > latter, the information will unconditionally appear in the string returned
> > by "getMessage". The contents of the "ExceptionContext" must be retrieved
> > manually because, as is the case for iterative solvers, it could lead to a
> > huge message.
> >
> Yes. Or even in some cases to "impossible" messages since it is
> totally unthinkable to compute the entries of the matrix underlying
> the general linear operator. In fact, for debugging purposes, printing
> the operator is not in my view necessary. For example, if the
> preconditioned conjugate gradient throws a
> NonPositiveDefiniteLinearOperatorException, I just need to know which
> one of the operator or its preconditioner was found not to be positive
> definite.
Do you mean that the context info for a (hyptohetical) method like
doSomething(LinearOperator a, LinearOperator b)
would be like
offending operator: a
or
offending operator: b
?
If so, is it not enough to just throw the exception? Won't it be obvious
which operator is "offending" by looking at the line number in the stack
trace?
> >
> > Thus, when debugging an application, one can catch the exception and loop
> > over the context keys using the "getKeys()" method, without needing to need
> > the key names in advance. [Thus I would keep the key names "private".]
> >
> OK, I understand. But we *do* document the keys, don't we? For
> example, would the Javadoc of the Conjugate Gradient method state
> which keys are used for what purpose?
In principle it would not hurt to have more detailed documentation.
Alternatively, we could introduce a general comment that "Additional
information on the failure is available in the exception context".
Best,
Gilles
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] Consistent use of ExceptionContext [was "using the
ExceptionContext facility"]
Posted by Sébastien Brisard <se...@m4x.org>.
Hi Gilles,
thanks for this answer.
>
> I am assuming that the main difference between using the "ExceptionContext"
> and passing information in the exception's constructor is that in the
> latter, the information will unconditionally appear in the string returned
> by "getMessage". The contents of the "ExceptionContext" must be retrieved
> manually because, as is the case for iterative solvers, it could lead to a
> huge message.
>
Yes. Or even in some cases to "impossible" messages since it is
totally unthinkable to compute the entries of the matrix underlying
the general linear operator. In fact, for debugging purposes, printing
the operator is not in my view necessary. For example, if the
preconditioned conjugate gradient throws a
NonPositiveDefiniteLinearOperatorException, I just need to know which
one of the operator or its preconditioner was found not to be positive
definite.
>
> Thus, when debugging an application, one can catch the exception and loop
> over the context keys using the "getKeys()" method, without needing to need
> the key names in advance. [Thus I would keep the key names "private".]
>
OK, I understand. But we *do* document the keys, don't we? For
example, would the Javadoc of the Conjugate Gradient method state
which keys are used for what purpose?
Best regards,
Sébastien
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] Consistent use of ExceptionContext [was "using the
ExceptionContext facility"]
Posted by Gilles Sadowski <gi...@harfang.homelinux.org>.
Hello Sébastien.
> >
> > One thing that I think we all agree on; however, is that we should not be
> > designing exceptions or APIs that throw exceptions with the intent that
> > applications catching exceptions should parse the messages or search
> > the message content for specific strings.
> >
> I do apologize, I am not sure I fully understand. Please let me try
> again. I agree, parsing e.getMessage() would be horrible, but that was
> not what I had in mind.
>
> Let's say that a NonPositiveDefiniteLinearOperatorException e is
> raised, and I want to retrieve the operator in question. One way to do
> it would be to have a getter
> e.getOffendingLinearOperator()
> In MATH-581, following the discussion entitled "Implementation of
> Conjugate Gradient (MATH-581)" (started aug, 4), we finally went for
> the more flexible
> e.getContext().getValue("offending operator")
I am assuming that the main difference between using the "ExceptionContext"
and passing information in the exception's constructor is that in the
latter, the information will unconditionally appear in the string returned
by "getMessage". The contents of the "ExceptionContext" must be retrieved
manually because, as is the case for iterative solvers, it could lead to a
huge message.
Thus, when debugging an application, one can catch the exception and loop
over the context keys using the "getKeys()" method, without needing to need
the key names in advance. [Thus I would keep the key names "private".]
> The issue then is a proper handling of the key names ("offending
> operator" in the present case). Should the key names be assigned
> arbitrarily by the method which throws the exception, or stored (as a
> constant String) in the exception itself. My point is that in some
> circumstances, it is possible to have the exception store "typical"
> keys, which can be consistently used by everyone throwing such an
> exception, with the further possibility to add supplementary context
> to this exception, with freely chosen key names.
It would be inconsistent to have two ways for accessing information stored
in an exception class (hard-coded strings vs accessors). The context was
primarily to be a "user" facility but I thought that it would come handy
if we want to avoid the risk of flooding the console.
One could view that that information stored in the exception context does
not strictly belong to the exception class; the exception is a "vehicle"
that allows more detailed (i.e. _too_ detailed in most cases) debugging
information to travel easily upwards.
Another point is that CM is not allowed to print non-localized messages.
I'd say that the exception context being printed on demand only, it could
stay away of the "LocalizedFormats" machinery without being a breach on the
requirement.
> [...]
Best regards,
Gilles
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] Consistent use of ExceptionContext [was "using the
ExceptionContext facility"]
Posted by Sébastien Brisard <se...@m4x.org>.
Yes. Multiple scenarios can lead to the same exception, and context
seems to be a very flexible feature for this kind of situations.
However, as you said, this should be invoked as last resort. Context
elements we are dead sure will always be passed to the exception
should be implemented as attributes. Others should be (well
documented) context keys.
I like your extreme example, by the way. I kind of remember that
Imageio has the same kind of features: filters are invoked by a
string. With the added difficulty that documentation was very
difficult to find.
Anyway, I'll post a proposal as soon as I have the rights.
Sébastien
2011/8/29 Phil Steitz <ph...@gmail.com>:
> On 8/28/11 11:56 PM, Sébastien Brisard wrote:
>> Hello everyone,
>> Looking at the present hierarchy of exceptions, I've had some further
>> thoughts, actually supporting the use of context rather than property
>> getters. Sticking with the same example, we have two exceptions
>> - NonPositiveDefiniteMatrixException: already implemented
>> - NonPositiveDefiniteLinearOperatorException: work in progress.
>> These two exceptions refer to the same mathematical concept, and the
>> former should probably extend the latter (just like AbstractRealMatrix
>> extends RealLinearOperator). However, these two exceptions are thrown
>> under quite different circumstances, with widely different parameters:
>> - If I understood correctly, NonPositiveDefiniteMatrixException is
>> thrown for example when a non-positive diagonal element is met,
>> - NonPositiveDefiniteLinearOperator is to be thrown when a *vector* x
>> is met, such as x'.a.x <= 0 (the entries of the operator as a matrix
>> are not accessible).
>> As you can see, the parameters of these exceptions will be different.
>> We could have a getOffendingOperator() method, but probably not a
>> getOffendingVector() method (since NonPositiveDefiniteMatrixException
>> has no offending vector in its state).
>>
>> Does that make sense?
>
> I see your point. Despite my conservative instincts [1], I think it
> may actually be best to make both the current properties of the
> matrix version and the new properties of operator version optional
> members of the exception context. There is nothing guaranteeing
> that the matrix version will always have a single diagonal element
> "witness." Current activations (which use this for strict, semi and
> normal positive-definiteness) always have a diagonal element and
> threshold defined, but there may be other activations where a norm
> or other test may be used to signal positive definiteness failure.
> I now think that the row, column and threshold property of
> NonPositiveDefiniteException should be moved to the exception
> context and the row and col should be collapsed into one (since it
> is always a diagonal element that witnesses the failure and what is
> reported is always the same). Regarding the operator version, we
> have two choices: keep the hierarchy corresponding to the math
> concept, or put the witness in the exception context. My first
> reaction was to drop the hierarchy (with justification that the
> numerical failures were different), but that only makes sense if
> there will *always* be a witness in the operator case. I am not
> sure about that, so I would say err on the side of flexibility and
> move the witness to the context.
>
> [1] I am probably too conservative on this because of bad
> experiences that I have had in the past with "data bags" of object
> properties used to avoid having to actually design things. While we
> are in no danger of doing this, imagine the wonderful idea that we
> stop talking about exceptions altogether and via the miracle of the
> exception context, we just have one exception. We define a NAME key
> and shove everything else into key/value pairs. That is a
> caricature and I don't really mean it seriously, but you get the
> point.
>
> Phil
>
>
>>
>> Best regards,
>> 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] Consistent use of ExceptionContext [was "using the ExceptionContext
facility"]
Posted by Phil Steitz <ph...@gmail.com>.
On 8/28/11 11:56 PM, Sébastien Brisard wrote:
> Hello everyone,
> Looking at the present hierarchy of exceptions, I've had some further
> thoughts, actually supporting the use of context rather than property
> getters. Sticking with the same example, we have two exceptions
> - NonPositiveDefiniteMatrixException: already implemented
> - NonPositiveDefiniteLinearOperatorException: work in progress.
> These two exceptions refer to the same mathematical concept, and the
> former should probably extend the latter (just like AbstractRealMatrix
> extends RealLinearOperator). However, these two exceptions are thrown
> under quite different circumstances, with widely different parameters:
> - If I understood correctly, NonPositiveDefiniteMatrixException is
> thrown for example when a non-positive diagonal element is met,
> - NonPositiveDefiniteLinearOperator is to be thrown when a *vector* x
> is met, such as x'.a.x <= 0 (the entries of the operator as a matrix
> are not accessible).
> As you can see, the parameters of these exceptions will be different.
> We could have a getOffendingOperator() method, but probably not a
> getOffendingVector() method (since NonPositiveDefiniteMatrixException
> has no offending vector in its state).
>
> Does that make sense?
I see your point. Despite my conservative instincts [1], I think it
may actually be best to make both the current properties of the
matrix version and the new properties of operator version optional
members of the exception context. There is nothing guaranteeing
that the matrix version will always have a single diagonal element
"witness." Current activations (which use this for strict, semi and
normal positive-definiteness) always have a diagonal element and
threshold defined, but there may be other activations where a norm
or other test may be used to signal positive definiteness failure.
I now think that the row, column and threshold property of
NonPositiveDefiniteException should be moved to the exception
context and the row and col should be collapsed into one (since it
is always a diagonal element that witnesses the failure and what is
reported is always the same). Regarding the operator version, we
have two choices: keep the hierarchy corresponding to the math
concept, or put the witness in the exception context. My first
reaction was to drop the hierarchy (with justification that the
numerical failures were different), but that only makes sense if
there will *always* be a witness in the operator case. I am not
sure about that, so I would say err on the side of flexibility and
move the witness to the context.
[1] I am probably too conservative on this because of bad
experiences that I have had in the past with "data bags" of object
properties used to avoid having to actually design things. While we
are in no danger of doing this, imagine the wonderful idea that we
stop talking about exceptions altogether and via the miracle of the
exception context, we just have one exception. We define a NAME key
and shove everything else into key/value pairs. That is a
caricature and I don't really mean it seriously, but you get the
point.
Phil
>
> Best regards,
> 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] Consistent use of ExceptionContext [was "using the
ExceptionContext facility"]
Posted by Sébastien Brisard <se...@m4x.org>.
Hello everyone,
Looking at the present hierarchy of exceptions, I've had some further
thoughts, actually supporting the use of context rather than property
getters. Sticking with the same example, we have two exceptions
- NonPositiveDefiniteMatrixException: already implemented
- NonPositiveDefiniteLinearOperatorException: work in progress.
These two exceptions refer to the same mathematical concept, and the
former should probably extend the latter (just like AbstractRealMatrix
extends RealLinearOperator). However, these two exceptions are thrown
under quite different circumstances, with widely different parameters:
- If I understood correctly, NonPositiveDefiniteMatrixException is
thrown for example when a non-positive diagonal element is met,
- NonPositiveDefiniteLinearOperator is to be thrown when a *vector* x
is met, such as x'.a.x <= 0 (the entries of the operator as a matrix
are not accessible).
As you can see, the parameters of these exceptions will be different.
We could have a getOffendingOperator() method, but probably not a
getOffendingVector() method (since NonPositiveDefiniteMatrixException
has no offending vector in its state).
Does that make sense?
Best regards,
Sébastien
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] Consistent use of ExceptionContext [was "using the
ExceptionContext facility"]
Posted by Sébastien Brisard <se...@m4x.org>.
Hello everyone,
>
> 0) key/value pairs that are "consistently used by everyone throwing
> such an exception" should be named properties of the exception. So
> in your example of the offending linear operator in
> NonPositiveDefiniteLinearOperatorException, the exception should
> expose a getOffendingOperator method.
> 1) key/value pairs that represent optional or context-variable
> properties of an exception *may* have key names defined in the class
> that throws the exception.
> 2) Whenever keys are "named" and included in API specification, we
> should ask whether or not specialized exceptions or named properties
> of the exceptions being thrown should be defined (i.e. it is a
> warning sign when these names surface in API documentation).
>
this sounds OK to me (I shall keep item 2 in mind). As I tried to
express earlier (Gilles actually did a better job at that than I did),
we went from a specialized getters solution to a "context-only"
solution in MATH-581
> > Let's say that a NonPositiveDefiniteLinearOperatorException e is
> > raised, and I want to retrieve the operator in question. One way to do
> > it would be to have a getter
> > e.getOffendingLinearOperator()
> > In MATH-581, following the discussion entitled "Implementation of
> > Conjugate Gradient (MATH-581)" (started aug, 4), we finally went for
> > the more flexible
> > e.getContext().getValue("offending operator")
>
> I am assuming that the main difference between using the "ExceptionContext"
> and passing information in the exception's constructor is that in the
> latter, the information will unconditionally appear in the string returned
> by "getMessage". The contents of the "ExceptionContext" must be retrieved
> manually because, as is the case for iterative solvers, it could lead to a
> huge message.
> Thus, when debugging an application, one can catch the exception and loop
> over the context keys using the "getKeys()" method, without needing to need
> the key names in advance. [Thus I would keep the key names "private".]
>
Phil's suggestion is a mixture of both, based on rule 2. I'm OK to go
(partly) back to the former solution (specialized getters), in fact
the former patch is still attached to the JIRA ticket, so it should
not be too much work...
I still have two questions
1. Gilles seems to be indicating that any object passed to the
exception's constructor should be printed in the exception's message,
which is absolutely unpractical in the present case (hence the choice
of context). My question is: is it a CM requirement that *all*
exception properties be printed by e.getMessage()? I looked for the
answer on the "CM Developers Guide", but did not find anything.
2. My second question refers to what Gilles said earlier
>
> Thus, when debugging an application, one can catch the exception and loop
> over the context keys using the "getKeys()" method, without needing to need
> the key names in advance. [Thus I would keep the key names "private".]
>
I am not sure about the meaning of "private" here. The way I see it:
the name of the key is attributed by the class which throws the
exception, not the exception itself (hence it is "private" from the
perspective of the exception itself). However, to the benefit of
end-users, I think the key name may be kept as a public final static
String within the class. Is that correct?
All the best for now,
Sébastien
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] Consistent use of ExceptionContext [was "using the ExceptionContext
facility"]
Posted by Phil Steitz <ph...@gmail.com>.
On 8/26/11 9:22 AM, Honton, Charles wrote:
> I recommend reviewing Chapter 9 "Exceptions" of Joshua Bloch's "Effective
> Java". In particular, look at Item 63, "Include Failure-Capture
> Information in Detail Messages".
Yes, +1 to that. We do a decent job of that now with exception
messages in [math], IMO. The feature we are discussing on this
thread provides a means to provide access to additional context
information that may be too large/unwieldy to include in exception
messages.
Phil
>
> Chas
>
>
> On 8/26/11 8:59 AM, "Phil Steitz" <ph...@gmail.com> wrote:
>
>> On 8/25/11 11:15 PM, Sébastien Brisard wrote:
>>> Hi,
>>>
>>>> One thing that I think we all agree on; however, is that we should not
>>>> be
>>>> designing exceptions or APIs that throw exceptions with the intent that
>>>> applications catching exceptions should parse the messages or search
>>>> the message content for specific strings.
>>>>
>>> I do apologize, I am not sure I fully understand. Please let me try
>>> again. I agree, parsing e.getMessage() would be horrible, but that was
>>> not what I had in mind.
>>>
>>> Let's say that a NonPositiveDefiniteLinearOperatorException e is
>>> raised, and I want to retrieve the operator in question. One way to do
>>> it would be to have a getter
>>> e.getOffendingLinearOperator()
>>> In MATH-581, following the discussion entitled "Implementation of
>>> Conjugate Gradient (MATH-581)" (started aug, 4), we finally went for
>>> the more flexible
>>> e.getContext().getValue("offending operator")
>>>
>>> The issue then is a proper handling of the key names ("offending
>>> operator" in the present case). Should the key names be assigned
>>> arbitrarily by the method which throws the exception, or stored (as a
>>> constant String) in the exception itself. My point is that in some
>>> circumstances, it is possible to have the exception store "typical"
>>> keys, which can be consistently used by everyone throwing such an
>>> exception, with the further possibility to add supplementary context
>>> to this exception, with freely chosen key names.
>>>
>>> Is it what you understood from my previous message?
>> I am sorry, Sebastien, I completely missed your point. I was
>> confusing message keys with context object keys. I now understand
>> what you are getting at. I agree with Gilles that user code
>> catching a contexted exception can just use getKeys to retrieve the
>> keys, but that leaves open the question of how the client code is
>> supposed to know what it is looking for. This may be an
>> over-simplification, but I would see the following as natural:
>>
>> 0) key/value pairs that are "consistently used by everyone throwing
>> such an exception" should be named properties of the exception. So
>> in your example of the offending linear operator in
>> NonPositiveDefiniteLinearOperatorException, the exception should
>> expose a getOffendingOperator method.
>> 1) key/value pairs that represent optional or context-variable
>> properties of an exception *may* have key names defined in the class
>> that throws the exception.
>> 2) Whenever keys are "named" and included in API specification, we
>> should ask whether or not specialized exceptions or named properties
>> of the exceptions being thrown should be defined (i.e. it is a
>> warning sign when these names surface in API documentation).
>>
>> Sorry I did not understand your original post and did not comment on
>> the earlier discussion.
>>
>> Phil
>>> Best regards,
>>> 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] Consistent use of ExceptionContext [was "using the
ExceptionContext facility"]
Posted by "Honton, Charles" <Ch...@intuit.com>.
I recommend reviewing Chapter 9 "Exceptions" of Joshua Bloch's "Effective
Java". In particular, look at Item 63, "Include Failure-Capture
Information in Detail Messages".
Chas
On 8/26/11 8:59 AM, "Phil Steitz" <ph...@gmail.com> wrote:
>On 8/25/11 11:15 PM, Sébastien Brisard wrote:
>> Hi,
>>
>>> One thing that I think we all agree on; however, is that we should not
>>>be
>>> designing exceptions or APIs that throw exceptions with the intent that
>>> applications catching exceptions should parse the messages or search
>>> the message content for specific strings.
>>>
>> I do apologize, I am not sure I fully understand. Please let me try
>> again. I agree, parsing e.getMessage() would be horrible, but that was
>> not what I had in mind.
>>
>> Let's say that a NonPositiveDefiniteLinearOperatorException e is
>> raised, and I want to retrieve the operator in question. One way to do
>> it would be to have a getter
>> e.getOffendingLinearOperator()
>> In MATH-581, following the discussion entitled "Implementation of
>> Conjugate Gradient (MATH-581)" (started aug, 4), we finally went for
>> the more flexible
>> e.getContext().getValue("offending operator")
>>
>> The issue then is a proper handling of the key names ("offending
>> operator" in the present case). Should the key names be assigned
>> arbitrarily by the method which throws the exception, or stored (as a
>> constant String) in the exception itself. My point is that in some
>> circumstances, it is possible to have the exception store "typical"
>> keys, which can be consistently used by everyone throwing such an
>> exception, with the further possibility to add supplementary context
>> to this exception, with freely chosen key names.
>>
>> Is it what you understood from my previous message?
>
>I am sorry, Sebastien, I completely missed your point. I was
>confusing message keys with context object keys. I now understand
>what you are getting at. I agree with Gilles that user code
>catching a contexted exception can just use getKeys to retrieve the
>keys, but that leaves open the question of how the client code is
>supposed to know what it is looking for. This may be an
>over-simplification, but I would see the following as natural:
>
>0) key/value pairs that are "consistently used by everyone throwing
>such an exception" should be named properties of the exception. So
>in your example of the offending linear operator in
>NonPositiveDefiniteLinearOperatorException, the exception should
>expose a getOffendingOperator method.
>1) key/value pairs that represent optional or context-variable
>properties of an exception *may* have key names defined in the class
>that throws the exception.
>2) Whenever keys are "named" and included in API specification, we
>should ask whether or not specialized exceptions or named properties
>of the exceptions being thrown should be defined (i.e. it is a
>warning sign when these names surface in API documentation).
>
>Sorry I did not understand your original post and did not comment on
>the earlier discussion.
>
>Phil
>> Best regards,
>> 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] Consistent use of ExceptionContext [was "using the ExceptionContext
facility"]
Posted by Phil Steitz <ph...@gmail.com>.
On 8/25/11 11:15 PM, Sébastien Brisard wrote:
> Hi,
>
>> One thing that I think we all agree on; however, is that we should not be
>> designing exceptions or APIs that throw exceptions with the intent that
>> applications catching exceptions should parse the messages or search
>> the message content for specific strings.
>>
> I do apologize, I am not sure I fully understand. Please let me try
> again. I agree, parsing e.getMessage() would be horrible, but that was
> not what I had in mind.
>
> Let's say that a NonPositiveDefiniteLinearOperatorException e is
> raised, and I want to retrieve the operator in question. One way to do
> it would be to have a getter
> e.getOffendingLinearOperator()
> In MATH-581, following the discussion entitled "Implementation of
> Conjugate Gradient (MATH-581)" (started aug, 4), we finally went for
> the more flexible
> e.getContext().getValue("offending operator")
>
> The issue then is a proper handling of the key names ("offending
> operator" in the present case). Should the key names be assigned
> arbitrarily by the method which throws the exception, or stored (as a
> constant String) in the exception itself. My point is that in some
> circumstances, it is possible to have the exception store "typical"
> keys, which can be consistently used by everyone throwing such an
> exception, with the further possibility to add supplementary context
> to this exception, with freely chosen key names.
>
> Is it what you understood from my previous message?
I am sorry, Sebastien, I completely missed your point. I was
confusing message keys with context object keys. I now understand
what you are getting at. I agree with Gilles that user code
catching a contexted exception can just use getKeys to retrieve the
keys, but that leaves open the question of how the client code is
supposed to know what it is looking for. This may be an
over-simplification, but I would see the following as natural:
0) key/value pairs that are "consistently used by everyone throwing
such an exception" should be named properties of the exception. So
in your example of the offending linear operator in
NonPositiveDefiniteLinearOperatorException, the exception should
expose a getOffendingOperator method.
1) key/value pairs that represent optional or context-variable
properties of an exception *may* have key names defined in the class
that throws the exception.
2) Whenever keys are "named" and included in API specification, we
should ask whether or not specialized exceptions or named properties
of the exceptions being thrown should be defined (i.e. it is a
warning sign when these names surface in API documentation).
Sorry I did not understand your original post and did not comment on
the earlier discussion.
Phil
> Best regards,
> 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] Consistent use of ExceptionContext [was "using the
ExceptionContext facility"]
Posted by Sébastien Brisard <se...@m4x.org>.
Hi,
>
> One thing that I think we all agree on; however, is that we should not be
> designing exceptions or APIs that throw exceptions with the intent that
> applications catching exceptions should parse the messages or search
> the message content for specific strings.
>
I do apologize, I am not sure I fully understand. Please let me try
again. I agree, parsing e.getMessage() would be horrible, but that was
not what I had in mind.
Let's say that a NonPositiveDefiniteLinearOperatorException e is
raised, and I want to retrieve the operator in question. One way to do
it would be to have a getter
e.getOffendingLinearOperator()
In MATH-581, following the discussion entitled "Implementation of
Conjugate Gradient (MATH-581)" (started aug, 4), we finally went for
the more flexible
e.getContext().getValue("offending operator")
The issue then is a proper handling of the key names ("offending
operator" in the present case). Should the key names be assigned
arbitrarily by the method which throws the exception, or stored (as a
constant String) in the exception itself. My point is that in some
circumstances, it is possible to have the exception store "typical"
keys, which can be consistently used by everyone throwing such an
exception, with the further possibility to add supplementary context
to this exception, with freely chosen key names.
Is it what you understood from my previous message?
Best regards,
Sébastien
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] Consistent use of ExceptionContext [was "using the ExceptionContext
facility"]
Posted by Phil Steitz <ph...@gmail.com>.
On 8/25/11 8:47 PM, Sébastien Brisard wrote:
> Hi,
> a while ago, I started a thread on the "proper" of keys in
> ExceptionContext. This message was too vague, and raised very (very)
> little interest. Hope this one will be more successful... I now have a
> suggestion, which would work in at least some cases.
>
> Very briefly, the issue is the following: the key names are attributed
> by the method which throws the exception (say iThrowTheException()).
> Now, the problem is: how does the method which catches the exception
> (say iCatchTheException()) make sense out of this key name? The answer
> would be to document the key names in the javadoc of
> iThrowTheException(). While very flexible this approach does not
> guarantee a minimum level of consistency.
>
> In some cases though, the potential context of a specific exception is
> known beforehand. For example, in
> o.a.c.m.linear.NonPositiveDefiniteLinearOperator, the context might be
> the so-called offending operator and offending vector. Then, I propose
> that key names be stored as public final static String and documented
> *in the exception definition*. For example, in
> NonPositiveDefiniteLinearOperator, we would have two constants
> public final static String OPERATOR = "operator"
> public final static String VECTOR = "vector"
>
> Thanks for your comments!
We have, I think it is fair to say, diverse views in the community
on the proper use of exception messages. One thing that I think we
all agree on; however, is that we should not be designing exceptions
or APIs that throw exceptions with the intent that applications
catching exceptions should parse the messages or search the message
content for specific strings. Those of us who like to include
informative exception error messages expect these to be logged or
visually inspected, not handled by client code. The vast majority
of valuable use cases for exception error messages are in debugging
code in development or diagnosing system failures, where
context-rich error messages can be invaluable. At runtime, the type
of the exception and any state that it holds in member fields (not
including the message) should be all that client code needs to know
to handle it. Therefore, I don't think it is necessary to repeat
all of the exception message strings in the API documentation for
the methods that may generate exceptions. Following standard
conventions, we should just fully document what exceptions may be
thrown and under which conditions these exceptions will be thrown.
Phil
> 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