| <?xml version="1.0"?> |
| |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| |
| <document url="exceptions.html"> |
| <properties> |
| <title>The Commons Math User Guide - Exceptions</title> |
| </properties> |
| <body> |
| <section name="19 Exceptions"> |
| |
| <subsection name="19.1 Overview" href="overview"> |
| Commons Math defines a set of exceptions in order to convey the |
| precise low-level cause of failure. |
| </subsection> |
| |
| <subsection name="19.2 Unchecked Exceptions" href="unchecked"> |
| <p> |
| Starting from version 3.0, all exceptions generated by the |
| Commons Math code are <em>unchecked</em> (i.e. they inherit from |
| the standard <code>RuntimeException</code> class). |
| The main rationale supporting this design decision is that the |
| exceptions generated in the library are not recoverable: They most |
| of the time result from bad input parameters or some failure due to |
| numerical problems. |
| A thorough discussion of the pros and cons of checked and unchecked |
| exceptions can be read in |
| <a href="http://www.mindview.net/Etc/Discussions/CheckedExceptions"> |
| this post</a> by Bruce Eckel. |
| </p> |
| </subsection> |
| |
| <subsection name="19.3 Hierarchies" href="hierarchies"> |
| <p> |
| The exceptions defined by Commons Math follow the Java standard |
| hierarchies: |
| <ul> |
| <li> |
| <a href="http://docs.oracle.com/javase/6/docs/api/java/lang/IllegalArgumentException.html"> |
| <code>IllegalArgumentException</code></a>: |
| A <a href="../commons-math-legacy-exception/apidocs/org/apache/commons/math4/legacy/exception/MathIllegalArgumentException.html"> |
| <code>MathIllegalArgumentException</code></a> is thrown when some input |
| parameter fails a precondition check. |
| </li> |
| <li> |
| <a href="http://docs.oracle.com/javase/6/docs/api/java/lang/IllegalStateException.html"> |
| <code>IllegalStateException</code></a>: |
| A <a href="../commons-math-legacy-exception/apidocs/org/apache/commons/math4/legacy/exception/MathIllegalStateException.html"> |
| <code>MathIllegalStateException</code></a> is thrown when some inconsistency |
| has been detected. |
| </li> |
| <li> |
| <a href="http://docs.oracle.com/javase/6/docs/api/java/lang/MathArithmeticException.html"> |
| <code>ArithmeticException</code></a>: |
| A <a href="../commons-math-legacy-exception/apidocs/org/apache/commons/math4/legacy/exception/MathArithmeticException.html"> |
| <code>MathArithmeticException</code></a> is thrown when conditions such as |
| "division by zero" or "overflow" are encountered. |
| </li> |
| <li> |
| <a href="http://docs.oracle.com/javase/6/docs/api/java/lang/MathUnsupportedOperationException.html"> |
| <code>UnsupportedOperationException</code></a>: |
| A <a href="../commons-math-legacy-exception/apidocs/org/apache/commons/math4/legacy/exception/MathUnsupportedOperationException.html"> |
| <code>MathUnsupportedOperationException</code></a> indicates that a feature |
| is missing or does not make sense in the given context. |
| </li> |
| </ul> |
| </p> |
| |
| <p> |
| In all of the above exception hierarchies, several subclasses can |
| exist, each conveying a specific underlying cause of the problem. |
| </p> |
| </subsection> |
| |
| <subsection name="19.4 Features" href="features"> |
| <ul> |
| <li>Localization |
| <p> |
| The detailed error messages (i.e. the string returned by the |
| <a href="http://docs.oracle.com/javase/6/docs/api/java/lang/Throwable.html#getLocalizedMessage()"> |
| getLocalizedMessage</a> method) can be localized. |
| However, besides the American/English default, French is the only language |
| for which a translation resource is available. |
| </p> |
| </li> |
| <li>Exception "context" |
| <p> |
| Every exception generated by Commons Math implements the |
| <a href="../commons-math-legacy-exception/apidocs/org/apache/commons/math4/legacy/exception/util/ExceptionContextProvider.html"> |
| ExceptionContextProvider</a> interface. A call to the |
| <a href="../commons-math-legacy-exception/apidocs/org/apache/commons/math4/legacy/exception/util/ExceptionContextProvider.html#getContext()"> |
| getContext</a> method will return the |
| <a href="../commons-math-legacy-exception/apidocs/org/apache/commons/math4/legacy/exception/util/ExceptionContext.html"> |
| ExceptionContext</a> instance stored in the exception, which the |
| user can further customize by adding messages and/or any object. |
| </p> |
| </li> |
| </ul> |
| </subsection> |
| |
| </section> |
| </body> |
| </document> |