<?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.
  -->
  
<?xml-stylesheet type="text/xsl" href="./xdoc.xsl"?>
<!-- $Id$ -->
<document url="exceptions.html">
  <properties>
    <title>The Commons Math User Guide - Exceptions</title>
  </properties>
  <body>
    <section name="16 Exceptions">

      <subsection name="16.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="16.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="16.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="../apidocs/org/apache/commons/math3/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="../apidocs/org/apache/commons/math3/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="../apidocs/org/apache/commons/math3/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="../apidocs/org/apache/commons/math3/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="16.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="../apidocs/org/apache/commons/math3/exception/util/ExceptionContextProvider.html">
                ExceptionContextProvider</a> interface. A call to the
              <a href="../apidocs/org/apache/commons/math3/exception/util/ExceptionContextProvider.html#getContext()">
                getContext</a> method will return the
              <a href="../apidocs/org/apache/commons/math3/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>
