src/site/xdoc/userguide/exceptions.xml - commons-math - Git at Google

 <?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>
	<?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>