You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by er...@apache.org on 2012/02/21 15:16:51 UTC
svn commit: r1291794 - in
/commons/proper/math/trunk/src/site/xdoc/userguide: exceptions.xml index.xml
Author: erans
Date: Tue Feb 21 14:16:51 2012
New Revision: 1291794
URL: http://svn.apache.org/viewvc?rev=1291794&view=rev
Log:
Added section on "exceptions".
Added:
commons/proper/math/trunk/src/site/xdoc/userguide/exceptions.xml (with props)
Modified:
commons/proper/math/trunk/src/site/xdoc/userguide/index.xml
Added: commons/proper/math/trunk/src/site/xdoc/userguide/exceptions.xml
URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/site/xdoc/userguide/exceptions.xml?rev=1291794&view=auto
==============================================================================
--- commons/proper/math/trunk/src/site/xdoc/userguide/exceptions.xml (added)
+++ commons/proper/math/trunk/src/site/xdoc/userguide/exceptions.xml Tue Feb 21 14:16:51 2012
@@ -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>
Propchange: commons/proper/math/trunk/src/site/xdoc/userguide/exceptions.xml
------------------------------------------------------------------------------
svn:eol-style = native
Modified: commons/proper/math/trunk/src/site/xdoc/userguide/index.xml
URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/site/xdoc/userguide/index.xml?rev=1291794&r1=1291793&r2=1291794&view=diff
==============================================================================
--- commons/proper/math/trunk/src/site/xdoc/userguide/index.xml (original)
+++ commons/proper/math/trunk/src/site/xdoc/userguide/index.xml Tue Feb 21 14:16:51 2012
@@ -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>