commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gilles Sadowski <gil...@harfang.homelinux.org>
Subject [Math] Explanations for MATH-459
Date Sat, 08 Jan 2011 21:54:06 GMT
Hi Michael.

The class
  org.apache.commons.math.MathRuntimeException
is deprecated. [All runtime exceptions used to be instantiated by static
methods in this class.]

The current policy is that a _specific_ exception must be thrown that best
describes the problem at hand. The classes in package "exception" should
cover every possible problem arising in Commons-Math.

As an example, whenever a file contains a statement like
---CUT---
import org.apache.commons.math.MathRuntimeException;
  if (value < min || value > max) {
    throw MathRuntime.createIllegalArgumentException(...);
  }
---CUT---
it must be replaced by something like
---CUT---
import org.apache.commons.math.exception.OutOfRangeException;
  if (value < min || value > max) {
    throw new OutOfRangeException(value, min, max);
  }
---CUT---

As a concrete example, let's take the class "BigFraction" (in package
"fraction"). Among others, it contains the following occurrences of
"MathRuntimeException":
(1)
---CUT---
  if (BigInteger.ZERO.equals(den)) {
    throw MathRuntimeException.createArithmeticException(LocalizedFormats.ZERO_DENOMINATOR);
  }
---CUT---

(2)
---CUT---
  if (Double.isNaN(value)) {
    throw MathRuntimeException.createIllegalArgumentException(LocalizedFormats.NAN_VALUE_CONVERSION);
  }
  if (Double.isInfinite(value)) {
    throw MathRuntimeException.createIllegalArgumentException(LocalizedFormats.INFINITE_VALUE_CONVERSION);
  }
---CUT---

In (1) you would replace it with
---CUT---
import org.apache.commons.math.exception.ZeroException;

  if (BigInteger.ZERO.equals(den)) {
    throw new ZeroException(LocalizedFormats.DENOMINATOR);
  }
---CUT---

In case (2), the two statements would become
---CUT---
import org.apache.commons.math.util.MathUtils;

  MathUtils.checkFinite(value);
---CUT---

Once the replacement are done, you must take care that the unit tests still
pass. Indeed in the above, we now throw an instance of "ZeroException"
instead of an instance of "ArithmeticException", so if a test expects one
and gets the other, it will fail: You then have to modify the "catch (...)"
statement so that is catches the right type of object.

Finally, you have to run "mvn clean test" to make sure that all the files
possibly affected by the changes have been updated.

Important caveat: Many exceptions thrown contain an additional message that
provide a more focused message about the context of the exception event;
this is the purpose of the "LocalizedFormats" enum. Some problems (to be
fixed before v3.0):
* Some of the enum constants duplicate the now more specific exception
  (an example of this is the "OutOfRangeException"); thus tey should not be
  used anymore.
* Some duplicate each other (i.e. different constants that basically say the
  same thing). All redundant constants will be removed some point.
If you look in the "LocalizedFormats" class, you'll see that some constants
are marked with a 
  /* keep */
comment, by which I signalled that the constant is used as a specific
context message within a "new-style" exception. Since they are to be kept,
these should be used in preference to any other that has the same meaning.


I hope I made it clearer what issue 459 is about.

Best regards,
Gilles

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org


Mime
View raw message