From 9a5b335e4237cc9a79f0cd481a557aeee51c5f53 Mon Sep 17 00:00:00 2001
From: Phil Steitz <psteitz@apache.org>
Date: Sun, 18 Jul 2004 23:57:11 +0000
Subject: [PATCH] Changed some methods to return interface types. Improved
 javadoc.

git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/math/trunk@141398 13f79535-47bb-0310-9956-ffa450edef68
---
 .../math/random/EmpiricalDistribution.java    | 41 ++++++++++++-------
 .../random/EmpiricalDistributionImpl.java     | 19 +++++----
 2 files changed, 37 insertions(+), 23 deletions(-)

diff --git a/src/java/org/apache/commons/math/random/EmpiricalDistribution.java b/src/java/org/apache/commons/math/random/EmpiricalDistribution.java
index 828310b70..70b53ae78 100644
--- a/src/java/org/apache/commons/math/random/EmpiricalDistribution.java
+++ b/src/java/org/apache/commons/math/random/EmpiricalDistribution.java
@@ -19,9 +19,9 @@ package org.apache.commons.math.random;
 import java.io.IOException;
 import java.io.File;
 import java.net.URL;
-import java.util.ArrayList;
+import java.util.List;
 
-import org.apache.commons.math.stat.univariate.SummaryStatistics;
+import org.apache.commons.math.stat.univariate.StatisticalSummary;
 
 /**
  * Represents an <a href="http://random.mat.sbg.ac.at/~ste/dipl/node11.html">
@@ -32,7 +32,6 @@ import org.apache.commons.math.stat.univariate.SummaryStatistics;
  * <i>distribution digests</i>, that describe empirical distributions and
  * support the following operations: <ul>
  * <li>loading the distribution from a file of observed data values</li>
- * <li>saving and re-loading distribution digests to/from "digest files" </li>
  * <li>dividing the input data into "bin ranges" and reporting bin frequency
  *     counts (data for histogram)</li>
  * <li>reporting univariate statistics describing the full set of data values
@@ -43,19 +42,22 @@ import org.apache.commons.math.stat.univariate.SummaryStatistics;
  * build grouped frequnecy histograms representing the input data or to
  * generate random values "like" those in the input file -- i.e., the values
  * generated will follow the distribution of the values in the file.
- * @version $Revision: 1.20 $ $Date: 2004/06/14 23:45:33 $
+ * 
+ * @version $Revision: 1.21 $ $Date: 2004/07/18 23:57:11 $
  */
 public interface EmpiricalDistribution {
 
     /**
      * Computes the empirical distribution from the provided
      * array of numbers.
+     * 
      * @param dataArray the data array
      */
     void load(double[] dataArray);
 
     /**
      * Computes the empirical distribution from the input file.
+     * 
      * @param file the input file
      * @throws IOException if an IO error occurs
      */
@@ -63,6 +65,7 @@ public interface EmpiricalDistribution {
 
     /**
      * Computes the empirical distribution using data read from a URL.
+     * 
      * @param url url of the input file
      * @throws IOException if an IO error occurs
      */
@@ -73,43 +76,51 @@ public interface EmpiricalDistribution {
      * <strong>Preconditions:</strong><ul>
      * <li>the distribution must be loaded before invoking this method</li></ul>
      * @return the random value.
+     * 
      * @throws IllegalStateException if the distribution has not been loaded
      */
     double getNextValue() throws IllegalStateException;
 
 
     /**
-     * Returns a DescriptiveStatistics describing this distribution.
+     * Returns a {@link StatisticalSummary} describing this distribution.
      * <strong>Preconditions:</strong><ul>
-     * <li>the distribution must be loaded before invoking this method</li></ul>
+     * <li>the distribution must be loaded before invoking this method</li>
+     * </ul>
+     * 
      * @return the sample statistics
      * @throws IllegalStateException if the distribution has not been loaded
      */
-    SummaryStatistics getSampleStats() throws IllegalStateException;
+    StatisticalSummary getSampleStats() throws IllegalStateException;
 
     /**
-     * property indicating whether or not the distribution has been loaded
+     * Property indicating whether or not the distribution has been loaded.
+     * 
      * @return true if the distribution has been loaded
      */
     boolean isLoaded();
 
      /**
-     * Returns the number of bins
-     * @return the number of bins.
+     * Returns the number of bins.
+     * 
+     * @return the number of bins
      */
     int getBinCount();
 
     /**
-     * Returns a list of Univariates containing statistics describing the
-     * values in each of the bins.  The ArrayList is indexed on the bin number.
-     * @return ArrayList of bin statistics.
+     * Returns a list of {@link SummaryStatistics} containing statistics
+     * describing the values in each of the bins.  The List is indexed on
+     * the bin number.
+     * 
+     * @return List of bin statistics
      */
-    ArrayList getBinStats();
+    List getBinStats();
 
     /**
      * Returns the array of upper bounds for the bins.  Bins are: <br/>
      * [min,upperBounds[0]],(upperBounds[0],upperBounds[1]],...,
-     *  (upperBounds[binCount-1],max]
+     *  (upperBounds[binCount-1],max].
+     * 
      * @return array of bin upper bounds
      */
     double[] getUpperBounds();
diff --git a/src/java/org/apache/commons/math/random/EmpiricalDistributionImpl.java b/src/java/org/apache/commons/math/random/EmpiricalDistributionImpl.java
index 157d8f824..f75025bc9 100644
--- a/src/java/org/apache/commons/math/random/EmpiricalDistributionImpl.java
+++ b/src/java/org/apache/commons/math/random/EmpiricalDistributionImpl.java
@@ -16,7 +16,6 @@
 
 package org.apache.commons.math.random;
 
-import java.util.ArrayList;
 import java.io.Serializable;
 import java.io.BufferedReader;
 import java.io.FileReader;
@@ -24,8 +23,11 @@ import java.io.File;
 import java.io.IOException;
 import java.io.InputStreamReader;
 import java.net.URL;
+import java.util.ArrayList;
+import java.util.List;
 
 import org.apache.commons.math.stat.univariate.SummaryStatistics;
+import org.apache.commons.math.stat.univariate.StatisticalSummary;
 
 /**
  * Implements <code>EmpiricalDistribution</code> interface.  This implementation
@@ -52,7 +54,7 @@ import org.apache.commons.math.stat.univariate.SummaryStatistics;
  *    entry per line.</li>
  * </ul></p>
  *
- * @version $Revision: 1.27 $ $Date: 2004/06/23 16:26:17 $
+ * @version $Revision: 1.28 $ $Date: 2004/07/18 23:57:11 $
  */
 public class EmpiricalDistributionImpl implements Serializable, EmpiricalDistribution {
 
@@ -407,14 +409,14 @@ public class EmpiricalDistributionImpl implements Serializable, EmpiricalDistrib
     }
 
     /**
-     * Returns a DescriptiveStatistics describing this distribution.
+     * Returns a {@link StatisticalSummary} describing this distribution.
      * <strong>Preconditions:</strong><ul>
      * <li>the distribution must be loaded before invoking this method</li></ul>
      * 
      * @return the sample statistics
      * @throws IllegalStateException if the distribution has not been loaded
      */
-    public SummaryStatistics getSampleStats() {
+    public StatisticalSummary getSampleStats() {
         return sampleStats;
     }
 
@@ -428,12 +430,13 @@ public class EmpiricalDistributionImpl implements Serializable, EmpiricalDistrib
     }
 
     /**
-     * Returns a list of Univariates containing statistics describing the
-     * values in each of the bins.  The ArrayList is indexed on the bin number.
+     * Returns an ArrayList of {@link SummaryStatistics} instances containing
+     * statistics describing the values in each of the bins.  The ArrayList is
+     * indexed on the bin number.
      * 
-     * @return ArrayList of bin statistics.
+     * @return List of bin statistics.
      */
-    public ArrayList getBinStats() {
+    public List getBinStats() {
         return binStats;
     }