On 2/1/11 6:38 AM, Stephen Colebourne wrote: > I can give some feedback based on JSR-310. > > I have a small hierarchy of exceptions that attempts to capture some > key problems that may occur. The problem I found was that as I > refactored code, the exceptions listed in Javadoc quickly became > inaccurate. As a result, I've started converting many exceptions to > the parent CalendricalException. If a method returns a subclasses of > CalEx then thats fine and provides more info. But documenting it as > returning the subclass is way too much work for limited gain. > > For [math], simply documenting MathException is sufficient. > MathRuntimeException, is unecessary as a name when all exceptions are > runtime (the correct decision). > > More generally, an obsession with having every piece of exception data > available via a variable is generally unhelpful. It simply leads to > large unmaintainable hierarchies and arguments like this one. It is > very rare to need the data. [math] is suffering because of localizing > exception, which IMO is a big mistake and the cause of a lot of the > issues. I am not sure really that the localization framework is the cause of significant issues for us. It does force us to maintain the messages and to maintain a top-level exception; but the problems we are having getting to consensus on design really have more to do with a) high-level vs low-level exception concepts and b) how much we can depend on messages (localized or not) to convey exception context and specialization information. We have been maintaining the messages for 2+ years now and this has not been a big deal, IMO. > In general, exceptions are for two purposes - info on failure and to > trap for retry. > > Info on failure simply needs a good message in English. No data is > required, although important (certainly not all!) pieces might be > captured. I agree with this; though the right data needs to be there. A canonical example is ArrayIndexOutOfBoundsException reporting the bad index in the message. The message should include a full statement of the failure *at the level of abstraction appropriate to the exception itself* > Trap for retry errors should be rare if present at all. I would much > prefer to see a proper result object which everyone is forced to check > to describe the success or failure of something that might be retried. "Retry" is not in general meaningful for our stuff, though in a small number of cases, "try a different algorithm" or "try a different starting point" , "adjust parameters and retry" or "return a special value" (all of which [math] code does internally at different places) can be reasonable.
What we report back to the application using [math] is that one of the following kinds of bad things has happened a) they have violated preconditions - they get MathIllegalArgumentException (same semantics as anywhere else) b) they have not violated preconditions, but a numerical problem has occurred (while not violating stated preconditions, their problem is not in the effective domain of the algorithm they asked [math] to execute) c) they have hit a bug in [math] Of course, we have no way of distinguishing b) and c) and a fair amount of our JIRA work really comes down to viewing b) problems as c) problems (increasing the effective domains of our implementations). > In general though, the main advice is to keep it simple. People rarely > use exception hierarchies. Mostly they want the message to be readable > to diagnose the problem in a stack trace. Agreed. This is why we had a very flat hierarchy through version 2.0 of [math]. Where we are having trouble gaining consensus is how to represent specializing context information in our exceptions and what abstractions to use to represent the shallow hierarchy that we aim to build. For example, in 2.0, we have a ConvergenceException, representing the commonly occurring scenario of type b) above where an iterative algorithm has failed to converge. This exception is often caught and wrapped or recovered from internally in [math]. It has a subclass, MaxEvaluationsExceededException to represent the common convergence failure suggested by its name. I personally think we should keep this exception in 3.0. Gilles thinks that we should replace it by more granular exceptions like "MaxCountExceeded" or "NotFiniteNumberException" (another reason that a sequence can fail to converge) that have nothing to do with convergence. We are similarly at odds regarding "FunctionEvaluationException" a top-level exception indicating that an error has occurred evaluating a function. > Finally, use the standard exceptions and patterns. IllegalArgumentEx > for example (which won't extend from MathEx, so does require separate > documentation). As in the guide, IllArgEx is for preconditions > mentioned in Javadoc or reasonably related to them, not general > calculation issues. > > Similarly, look at the standard JDK executor framework > (ExecutionException) to understand the necessity to wrap callbacks. > Thanks, Stephen! Phil --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
