Re: [Math] Localization and Error Handling

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

Luc Maisonobe wrote:
> Gilles Sadowski a écrit :
>> Hi.
>>
>> [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,
>> Gilles
>>
>> [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.
> 
> Perhaps you could open a Jira issue and attach your patch to it, so we
> can all have a look at it. If we agree to it, then we could start a
> branch on svn for this huge modification.

Or transition to it incrementally in trunk if that is possible.
Maintaining multiple branches that differ only in exception
management with the level of activity that we have would be a pain.

+1 to having a look at a patch.  ++1 if we can find some middle
ground between extremes and a transition path.

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