Added section on "exceptions".
git-svn-id: https://svn.apache.org/repos/asf/commons/proper/math/trunk@1291794 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Gilles Sadowski
parent
f1314b1019
commit
bc2588f16d
|
|
@ -0,0 +1,120 @@
|
|||
<?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>
|
||||
|
|
@ -28,7 +28,7 @@
|
|||
<section name="Table of Contents" href="toc">
|
||||
|
||||
<ul>
|
||||
<li><a href="overview.html">0. Overview</a>
|
||||
<li><a href="overview.html">0. Overview</a>
|
||||
<ul>
|
||||
<li><a href="overview.html#a0.1_About_the_User_Guide">0.1 About the User Guide</a></li>
|
||||
<li><a href="overview.html#a0.2_Whats_in_commons-math">0.2 What's in commons-math</a></li>
|
||||
|
|
@ -141,12 +141,21 @@
|
|||
<li><a href="genetics.html#a14.1_Overview">14.1 Overview</a></li>
|
||||
<li><a href="genetics.html#a14.2_GA_Framework">14.2 GA Framework</a></li>
|
||||
<li><a href="genetics.html#a14.3_Implementation">14.3 Implementation and Examples</a></li>
|
||||
</ul></li>
|
||||
<li><a href="filter.html">15. Filters</a>
|
||||
<ul>
|
||||
<li><a href="filter.html#a15.1_Overview">15.1 Overview</a></li>
|
||||
<li><a href="filter.html#a15.2_Kalman_Filter">15.2 Kalman Filter</a></li>
|
||||
</ul></li>
|
||||
</ul></li>
|
||||
<li><a href="filter.html">15. Filters</a>
|
||||
<ul>
|
||||
<li><a href="filter.html#a15.1_Overview">15.1 Overview</a></li>
|
||||
<li><a href="filter.html#a15.2_Kalman_Filter">15.2 Kalman Filter</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="exceptions.html">16. Exceptions</a>
|
||||
<ul>
|
||||
<li><a href="exceptions.html#a16.1_Overview">16.1 Overview</a></li>
|
||||
<li><a href="exceptions.html#a16.2_Unchecked_Exceptions">16.2 Unchecked Exceptions</a></li>
|
||||
<li><a href="exceptions.html#a16.3_Hierarchies">16.3 Hierarchies</a></li>
|
||||
<li><a href="exceptions.html#a16.4_Features">16.4 Features</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</section>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue