commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gilles Sadowski <>
Subject Re: [Math] Localization and Error Handling
Date Wed, 31 Mar 2010 11:38:15 GMT

[I'm not quoting previous messages because the mix of quotes and wrapped
lines has become illegible.]

I'll first list all of the problems (IMO) in the current handling of error
reporting. Then I'll propose modifications that will hopefully solve them.

Difficulties for the CM developers:
1. The message patterns appear in every exception instantiation.
2. The developer must correctly reproduce the pattern. Doing this by hand or
   by copy/paste is error-prone.
3. The developer must search the (long) list of available patterns in order
   to determine if one already exists that provides what he needs.
4. Localized message patterns contain Unicode escapes.

Difficulties for the application-programmer using CM:
5. Different patterns actually report the same error type.
6. Many different errors are instantiated with an indiscriminate
   "IllegalArgumentException". This prevents flexible access to the cause
   of the error as it is only available as a "String".
7. As a consequence of point 6, the message reported to the end-user, as
   generated by CM, might not be consistent with the user action (at the
   higher-level application) that generated the error.
8. A variant of point 7: the application programmer should be free to
   design his own formatting of error messages (e.g. he might want to have
   all messages with an upper-cased first letter).
9. The patterns are not consistent: some start with an uppercase letter,
   some with a lower-case; in some cases, there is an upper-case letter in
   the English version, but not in the French version.

Difficulty for some end-users:
10. Using a default non-English locale, while still wanting to have all
    error messages output in English.

Those are not big problems, and could be dismissed as unimportant details;
however, any library seeking wide use should promote the best practices,
even in those little corners.
I think that we can improve over the current way in all of the situations
cited above.

I have the impression that the current way is the result of writing the
library around the localization feature instead of adding the feature to the
library's "core business".
Localisation is a high-level feature and should be as little intrusive as
possible for those users who don't need it.[1]
For those who actually need it, it should not be CM's decision as to what
degree of flexibility is actually useful.

Here what I propose:
 * At the level of CM, the building blocks for error reporting should be
   classes derived from (modified) "MathException" and
   "MathRuntimeException" classes[2].
 * Each exception class will represent a specific problem (e.g.
   "OutOfRangeException") and will belongs in an "exception" package.
 * The specific exception classes will provide accessors to the data
   relevant to the problem (e.g. methods "getLo()" and "getHi()" will
   respectively return the lower and higher bounds of the allowed interval,
   in the case of an "OutOfRangeException").
 * To enforce the use of meaningful exceptions throughout CM, the base
   classes constructors' access should be "protected".
 * Only the 2 base classes will deal with constructing an error message and
   will store an "enum" (e.g. "MathMessageKey.OUT_OF_RANGE") that will
   uniquely identify a pattern to be used for message formatting.
 * To enable localization, the base classes will delegate the actual
   formatting to a "Framework" interface. The actual class implementing the
   "Framework" can be selected at runtime, so that the user can choose from
   a default ("resources"-free) formatting or a localized one (with a
   possible dependency to an external library, for maximum flexibility).

[In order not to add to an already long post, I won't detail how this
proposal will obviously improve on the problems enumerated above.]
Please let me know what you think.

Best regards,

[1] There is even the case where a user might not even *want* any code 
    accessing "resources".
[2] For the moment, I'll leave aside another problem: the choice of which
    errors should be inherited from "RuntimeException" and the fact that
    this choice is not consistent in CM. As changes in order to correct this
    will not be backward-compatible, it is left for another dicussion and
    for a major version bump.

P.S. I have a prototype that partially implements these ideas. But I'm not
     sure how to proceed in order to demonstrate it, as it would also
     include configuration changes ("compile" vs "runtime") and it must
     create separate JARs for the alternative "Framework" implementations.

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message