Mailing-List: contact dev-help@commons.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "Commons Developers List" <dev@commons.apache.org>
Received-SPF: pass (athena.apache.org: domain of phil.steitz@gmail.com
 designates 209.85.161.171 as permitted sender)
Message-ID: <4E572E72.80001@gmail.com>
Date: Thu, 25 Aug 2011 22:26:10 -0700
From: Phil Steitz <phil.steitz@gmail.com>
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.7;
 rv:6.0) Gecko/20110812 Thunderbird/6.0
MIME-Version: 1.0
To: Commons Developers List <dev@commons.apache.org>
Subject: Re: [math] Consistent use of ExceptionContext [was "using the
 ExceptionContext
 facility"]
References: 
 <CAGRH7HpOHY6CSy584podiApoy45souvureSZsX6pNeyi-GtOSw@mail.gmail.com>
In-Reply-To: 
 <CAGRH7HpOHY6CSy584podiApoy45souvureSZsX6pNeyi-GtOSw@mail.gmail.com>
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: 8bit

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