From b883dcbc08044687bc037ed2170f18416893f7d0 Mon Sep 17 00:00:00 2001 From: Luc Maisonobe Date: Mon, 10 Sep 2012 14:47:45 +0000 Subject: [PATCH] Updated throws declaration for random package (and part of distribution). git-svn-id: https://svn.apache.org/repos/asf/commons/proper/math/trunk@1382904 13f79535-47bb-0310-9956-ffa450edef68 --- .../math3/distribution/GammaDistribution.java | 4 +- .../math3/exception/NotANumberException.java | 38 +++++++ .../exception/util/LocalizedFormats.java | 1 + .../commons/math3/random/RandomData.java | 84 ++++++++-------- .../math3/random/RandomDataGenerator.java | 99 ++++++++++++------- .../commons/math3/random/RandomDataImpl.java | 84 ++++++++++------ .../math3/random/StableRandomGenerator.java | 8 +- .../commons/math3/random/ValueServer.java | 41 +++++--- 8 files changed, 240 insertions(+), 119 deletions(-) create mode 100644 src/main/java/org/apache/commons/math3/exception/NotANumberException.java diff --git a/src/main/java/org/apache/commons/math3/distribution/GammaDistribution.java b/src/main/java/org/apache/commons/math3/distribution/GammaDistribution.java index 7670aec8a..9b4d9fee3 100644 --- a/src/main/java/org/apache/commons/math3/distribution/GammaDistribution.java +++ b/src/main/java/org/apache/commons/math3/distribution/GammaDistribution.java @@ -86,8 +86,10 @@ public class GammaDistribution extends AbstractRealDistribution { * * @param shape the shape parameter * @param scale the scale parameter + * @throws NotStrictlyPositiveException if {@code shape <= 0} or + * {@code scale <= 0}. */ - public GammaDistribution(double shape, double scale) { + public GammaDistribution(double shape, double scale) throws NotStrictlyPositiveException { this(shape, scale, DEFAULT_INVERSE_ABSOLUTE_ACCURACY); } diff --git a/src/main/java/org/apache/commons/math3/exception/NotANumberException.java b/src/main/java/org/apache/commons/math3/exception/NotANumberException.java new file mode 100644 index 000000000..cd1a6f82b --- /dev/null +++ b/src/main/java/org/apache/commons/math3/exception/NotANumberException.java @@ -0,0 +1,38 @@ +/* + * 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. + */ +package org.apache.commons.math3.exception; + +import org.apache.commons.math3.exception.util.LocalizedFormats; + +/** + * Exception to be thrown when a number is not a n umber. + * + * @since 3.0 + * @version $Id$ + */ +public class NotANumberException extends MathIllegalNumberException { + /** Serializable version Id. */ + private static final long serialVersionUID = 20120906L; + + /** + * Construct the exception. + */ + public NotANumberException() { + super(LocalizedFormats.NAN_NOT_ALLOWED, Double.NaN); + } + +} diff --git a/src/main/java/org/apache/commons/math3/exception/util/LocalizedFormats.java b/src/main/java/org/apache/commons/math3/exception/util/LocalizedFormats.java index 304c2fa35..27c21fbc3 100644 --- a/src/main/java/org/apache/commons/math3/exception/util/LocalizedFormats.java +++ b/src/main/java/org/apache/commons/math3/exception/util/LocalizedFormats.java @@ -126,6 +126,7 @@ public enum LocalizedFormats implements Localizable { INITIAL_CAPACITY_NOT_POSITIVE("initial capacity ({0}) is not positive"), INITIAL_COLUMN_AFTER_FINAL_COLUMN("initial column {1} after final column {0}"), INITIAL_ROW_AFTER_FINAL_ROW("initial row {1} after final row {0}"), + @Deprecated INPUT_DATA_FROM_UNSUPPORTED_DATASOURCE("input data comes from unsupported datasource: {0}, supported sources: {1}, {2}"), INSTANCES_NOT_COMPARABLE_TO_EXISTING_VALUES("instance of class {0} not comparable to existing values"), INSUFFICIENT_DATA_FOR_T_STATISTIC("insufficient data for t statistic, needs at least 2, got {0}"), diff --git a/src/main/java/org/apache/commons/math3/random/RandomData.java b/src/main/java/org/apache/commons/math3/random/RandomData.java index 1cba7e2c2..126da3196 100644 --- a/src/main/java/org/apache/commons/math3/random/RandomData.java +++ b/src/main/java/org/apache/commons/math3/random/RandomData.java @@ -18,6 +18,11 @@ package org.apache.commons.math3.random; import java.util.Collection; +import org.apache.commons.math3.exception.NotANumberException; +import org.apache.commons.math3.exception.NotFiniteNumberException; +import org.apache.commons.math3.exception.NotStrictlyPositiveException; +import org.apache.commons.math3.exception.NumberIsTooLargeException; + /** * Random data generation utilities. * @deprecated to be removed in 4.0. Use {@link RandomDataGenerator} directly @@ -34,10 +39,10 @@ public interface RandomData { * * @param len the length of the string to be generated * @return a random string of hex characters of length {@code len} - * @throws org.apache.commons.math3.exception.NotStrictlyPositiveException + * @throws NotStrictlyPositiveException * if {@code len <= 0} */ - String nextHexString(int len); + String nextHexString(int len) throws NotStrictlyPositiveException; /** * Generates a uniformly distributed random integer between {@code lower} @@ -52,10 +57,9 @@ public interface RandomData { * @param upper upper bound for generated integer * @return a random integer greater than or equal to {@code lower} * and less than or equal to {@code upper} - * @throws org.apache.commons.math3.exception.NumberIsTooLargeException - * if {@code lower >= upper} + * @throws NumberIsTooLargeException if {@code lower >= upper} */ - int nextInt(int lower, int upper); + int nextInt(int lower, int upper) throws NumberIsTooLargeException; /** * Generates a uniformly distributed random long integer between @@ -70,10 +74,9 @@ public interface RandomData { * @param upper upper bound for generated long integer * @return a random long integer greater than or equal to {@code lower} and * less than or equal to {@code upper} - * @throws org.apache.commons.math3.exception.NumberIsTooLargeException - * if {@code lower >= upper}. + * @throws NumberIsTooLargeException if {@code lower >= upper} */ - long nextLong(long lower, long upper); + long nextLong(long lower, long upper) throws NumberIsTooLargeException; /** * Generates a random string of hex characters from a secure random @@ -85,10 +88,9 @@ public interface RandomData { * * @param len the length of the string to be generated * @return a random string of hex characters of length {@code len} - * @throws org.apache.commons.math3.exception.NotStrictlyPositiveException - * if {@code len <= 0} + * @throws NotStrictlyPositiveException if {@code len <= 0} */ - String nextSecureHexString(int len); + String nextSecureHexString(int len) throws NotStrictlyPositiveException; /** * Generates a uniformly distributed random integer between {@code lower} @@ -106,10 +108,9 @@ public interface RandomData { * @param upper upper bound for generated integer * @return a random integer greater than or equal to {@code lower} and less * than or equal to {@code upper}. - * @throws org.apache.commons.math3.exception.NumberIsTooLargeException - * if {@code lower >= upper}. + * @throws NumberIsTooLargeException if {@code lower >= upper}. */ - int nextSecureInt(int lower, int upper); + int nextSecureInt(int lower, int upper) throws NumberIsTooLargeException; /** * Generates a uniformly distributed random long integer between @@ -128,10 +129,9 @@ public interface RandomData { * @param upper upper bound for generated integer * @return a random long integer greater than or equal to {@code lower} and * less than or equal to {@code upper}. - * @throws org.apache.commons.math3.exception.NumberIsTooLargeException - * if {@code lower >= upper}. + * @throws NumberIsTooLargeException if {@code lower >= upper}. */ - long nextSecureLong(long lower, long upper); + long nextSecureLong(long lower, long upper) throws NumberIsTooLargeException; /** * Generates a random value from the Poisson distribution with the given @@ -143,10 +143,9 @@ public interface RandomData { * * @param mean the mean of the Poisson distribution * @return a random value following the specified Poisson distribution - * @throws org.apache.commons.math3.exception.NotStrictlyPositiveException - * if {@code mean <= 0}. + * @throws NotStrictlyPositiveException if {@code mean <= 0}. */ - long nextPoisson(double mean); + long nextPoisson(double mean) throws NotStrictlyPositiveException; /** * Generates a random value from the Normal (or Gaussian) distribution with @@ -159,10 +158,9 @@ public interface RandomData { * @param mu the mean of the distribution * @param sigma the standard deviation of the distribution * @return a random value following the specified Gaussian distribution - * @throws org.apache.commons.math3.exception.NotStrictlyPositiveException - * if {@code sigma <= 0}. + * @throws NotStrictlyPositiveException if {@code sigma <= 0}. */ - double nextGaussian(double mu, double sigma); + double nextGaussian(double mu, double sigma) throws NotStrictlyPositiveException; /** * Generates a random value from the exponential distribution @@ -174,10 +172,9 @@ public interface RandomData { * * @param mean the mean of the distribution * @return a random value following the specified exponential distribution - * @throws org.apache.commons.math3.exception.NotStrictlyPositiveException - * if {@code mean <= 0}. + * @throws NotStrictlyPositiveException if {@code mean <= 0}. */ - double nextExponential(double mean); + double nextExponential(double mean) throws NotStrictlyPositiveException; /** * Generates a uniformly distributed random value from the open interval @@ -193,10 +190,12 @@ public interface RandomData { * @param upper the exclusive upper bound of the support * @return a uniformly distributed random value between lower and upper * (exclusive) - * @throws org.apache.commons.math3.exception.NumberIsTooLargeException - * if {@code lower >= upper} + * @throws NumberIsTooLargeException if {@code lower >= upper} + * @throws NotFiniteNumberException if one of the bounds is infinite + * @throws NotANumberException if one of the bounds is infinite */ - double nextUniform(double lower, double upper); + double nextUniform(double lower, double upper) + throws NumberIsTooLargeException, NotFiniteNumberException, NotANumberException; /** * Generates a uniformly distributed random value from the interval @@ -217,10 +216,12 @@ public interface RandomData { * interval, if {@code lowerInclusive} is {@code false}, or in the * {@code [lower, upper)} interval, if {@code lowerInclusive} is * {@code true} - * @throws org.apache.commons.math3.exception.NumberIsTooLargeException - * if {@code lower >= upper} + * @throws NumberIsTooLargeException if {@code lower >= upper} + * @throws NotFiniteNumberException if one of the bounds is infinite + * @throws NotANumberException if one of the bounds is infinite */ - double nextUniform(double lower, double upper, boolean lowerInclusive); + double nextUniform(double lower, double upper, boolean lowerInclusive) + throws NumberIsTooLargeException, NotFiniteNumberException, NotANumberException; /** * Generates an integer array of length {@code k} whose entries are selected @@ -234,12 +235,11 @@ public interface RandomData { * @param k the size of the permutation * @return a random {@code k}-permutation of {@code n}, as an array of * integers - * @throws org.apache.commons.math3.exception.NumberIsTooLargeException - * if {@code k > n}. - * @throws org.apache.commons.math3.exception.NotStrictlyPositiveException - * if {@code k <= 0}. + * @throws NumberIsTooLargeException if {@code k > n}. + * @throws NotStrictlyPositiveException if {@code k <= 0}. */ - int[] nextPermutation(int n, int k); + int[] nextPermutation(int n, int k) + throws NumberIsTooLargeException, NotStrictlyPositiveException; /** * Returns an array of {@code k} objects selected randomly from the @@ -255,10 +255,10 @@ public interface RandomData { * @param c the collection to be sampled * @param k the size of the sample * @return a random sample of {@code k} elements from {@code c} - * @throws org.apache.commons.math3.exception.NumberIsTooLargeException - * if {@code k > c.size()}. - * @throws org.apache.commons.math3.exception.NotStrictlyPositiveException - * if {@code k <= 0}. + * @throws NumberIsTooLargeException if {@code k > c.size()}. + * @throws NotStrictlyPositiveException if {@code k <= 0}. */ - Object[] nextSample(Collection c, int k); + Object[] nextSample(Collection c, int k) + throws NumberIsTooLargeException, NotStrictlyPositiveException; + } diff --git a/src/main/java/org/apache/commons/math3/random/RandomDataGenerator.java b/src/main/java/org/apache/commons/math3/random/RandomDataGenerator.java index 21647b014..814d5390c 100644 --- a/src/main/java/org/apache/commons/math3/random/RandomDataGenerator.java +++ b/src/main/java/org/apache/commons/math3/random/RandomDataGenerator.java @@ -38,9 +38,12 @@ import org.apache.commons.math3.distribution.TDistribution; import org.apache.commons.math3.distribution.WeibullDistribution; import org.apache.commons.math3.distribution.ZipfDistribution; import org.apache.commons.math3.exception.MathInternalError; +import org.apache.commons.math3.exception.NotANumberException; +import org.apache.commons.math3.exception.NotFiniteNumberException; +import org.apache.commons.math3.exception.NotPositiveException; import org.apache.commons.math3.exception.NotStrictlyPositiveException; -import org.apache.commons.math3.exception.MathIllegalArgumentException; import org.apache.commons.math3.exception.NumberIsTooLargeException; +import org.apache.commons.math3.exception.OutOfRangeException; import org.apache.commons.math3.exception.util.LocalizedFormats; import org.apache.commons.math3.util.FastMath; @@ -155,7 +158,7 @@ public class RandomDataGenerator implements RandomData, Serializable { * @return the random string. * @throws NotStrictlyPositiveException if {@code len <= 0}. */ - public String nextHexString(int len) { + public String nextHexString(int len) throws NotStrictlyPositiveException { if (len <= 0) { throw new NotStrictlyPositiveException(LocalizedFormats.LENGTH, len); } @@ -191,9 +194,9 @@ public class RandomDataGenerator implements RandomData, Serializable { } /** {@inheritDoc} */ - public int nextInt(int lower, int upper) { + public int nextInt(int lower, int upper) throws NumberIsTooLargeException { if (lower >= upper) { - throw new MathIllegalArgumentException(LocalizedFormats.LOWER_BOUND_NOT_BELOW_UPPER_BOUND, + throw new NumberIsTooLargeException(LocalizedFormats.LOWER_BOUND_NOT_BELOW_UPPER_BOUND, lower, upper, false); } double r = getRan().nextDouble(); @@ -202,9 +205,9 @@ public class RandomDataGenerator implements RandomData, Serializable { } /** {@inheritDoc} */ - public long nextLong(long lower, long upper) { + public long nextLong(long lower, long upper) throws NumberIsTooLargeException { if (lower >= upper) { - throw new MathIllegalArgumentException(LocalizedFormats.LOWER_BOUND_NOT_BELOW_UPPER_BOUND, + throw new NumberIsTooLargeException(LocalizedFormats.LOWER_BOUND_NOT_BELOW_UPPER_BOUND, lower, upper, false); } double r = getRan().nextDouble(); @@ -227,8 +230,9 @@ public class RandomDataGenerator implements RandomData, Serializable { * Each byte of the binary digest is converted to 2 hex digits. * *

+ * @throws NotStrictlyPositiveException if {@code len <= 0} */ - public String nextSecureHexString(int len) { + public String nextSecureHexString(int len) throws NotStrictlyPositiveException { if (len <= 0) { throw new NotStrictlyPositiveException(LocalizedFormats.LENGTH, len); } @@ -278,7 +282,7 @@ public class RandomDataGenerator implements RandomData, Serializable { } /** {@inheritDoc} */ - public int nextSecureInt(int lower, int upper) { + public int nextSecureInt(int lower, int upper) throws NumberIsTooLargeException { if (lower >= upper) { throw new NumberIsTooLargeException(LocalizedFormats.LOWER_BOUND_NOT_BELOW_UPPER_BOUND, lower, upper, false); @@ -290,7 +294,7 @@ public class RandomDataGenerator implements RandomData, Serializable { } /** {@inheritDoc} */ - public long nextSecureLong(long lower, long upper) { + public long nextSecureLong(long lower, long upper) throws NumberIsTooLargeException { if (lower >= upper) { throw new NumberIsTooLargeException(LocalizedFormats.LOWER_BOUND_NOT_BELOW_UPPER_BOUND, lower, upper, false); @@ -313,15 +317,16 @@ public class RandomDataGenerator implements RandomData, Serializable { *
  • For large means, uses the rejection algorithm described in
    * Devroye, Luc. (1981).The Computer Generation of Poisson Random Variables * Computing vol. 26 pp. 197-207.

    • + * @throws NotStrictlyPositiveException if {@code len <= 0} */ - public long nextPoisson(double mean) { + public long nextPoisson(double mean) throws NotStrictlyPositiveException { return new PoissonDistribution(getRan(), mean, PoissonDistribution.DEFAULT_EPSILON, PoissonDistribution.DEFAULT_MAX_ITERATIONS).sample(); } /** {@inheritDoc} */ - public double nextGaussian(double mu, double sigma) { + public double nextGaussian(double mu, double sigma) throws NotStrictlyPositiveException { if (sigma <= 0) { throw new NotStrictlyPositiveException(LocalizedFormats.STANDARD_DEVIATION, sigma); } @@ -339,7 +344,7 @@ public class RandomDataGenerator implements RandomData, Serializable { * Communications of the ACM, 15, 873-882. *

    */ - public double nextExponential(double mean) { + public double nextExponential(double mean) throws NotStrictlyPositiveException { return new ExponentialDistribution(getRan(), mean, ExponentialDistribution.DEFAULT_INVERSE_ABSOLUTE_ACCURACY).sample(); } @@ -363,8 +368,10 @@ public class RandomDataGenerator implements RandomData, Serializable { * @param shape the median of the Gamma distribution * @param scale the scale parameter of the Gamma distribution * @return random value sampled from the Gamma(shape, scale) distribution + * @throws NotStrictlyPositiveException if {@code shape <= 0} or + * {@code scale <= 0}. */ - public double nextGamma(double shape, double scale) { + public double nextGamma(double shape, double scale) throws NotStrictlyPositiveException { return new GammaDistribution(getRan(),shape, scale, GammaDistribution.DEFAULT_INVERSE_ABSOLUTE_ACCURACY).sample(); } @@ -376,8 +383,12 @@ public class RandomDataGenerator implements RandomData, Serializable { * @param numberOfSuccesses number of successes in the population of the Hypergeometric distribution * @param sampleSize the sample size of the Hypergeometric distribution * @return random value sampled from the Hypergeometric(numberOfSuccesses, sampleSize) distribution + * @throws NumberIsTooLargeException if {@code numberOfSuccesses > populationSize}, + * or {@code sampleSize > populationSize}. + * @throws NotStrictlyPositiveException if {@code populationSize <= 0}. + * @throws NotPositiveException if {@code numberOfSuccesses < 0}. */ - public int nextHypergeometric(int populationSize, int numberOfSuccesses, int sampleSize) { + public int nextHypergeometric(int populationSize, int numberOfSuccesses, int sampleSize) throws NotPositiveException, NotStrictlyPositiveException, NumberIsTooLargeException { return new HypergeometricDistribution(getRan(),populationSize, numberOfSuccesses, sampleSize).sample(); } @@ -388,8 +399,11 @@ public class RandomDataGenerator implements RandomData, Serializable { * @param r the number of successes of the Pascal distribution * @param p the probability of success of the Pascal distribution * @return random value sampled from the Pascal(r, p) distribution + * @throws NotStrictlyPositiveException if the number of successes is not positive + * @throws OutOfRangeException if the probability of success is not in the + * range {@code [0, 1]}. */ - public int nextPascal(int r, double p) { + public int nextPascal(int r, double p) throws NotStrictlyPositiveException, OutOfRangeException { return new PascalDistribution(getRan(), r, p).sample(); } @@ -398,8 +412,9 @@ public class RandomDataGenerator implements RandomData, Serializable { * * @param df the degrees of freedom of the T distribution * @return random value from the T(df) distribution + * @throws NotStrictlyPositiveException if {@code df <= 0} */ - public double nextT(double df) { + public double nextT(double df) throws NotStrictlyPositiveException { return new TDistribution(getRan(), df, TDistribution.DEFAULT_INVERSE_ABSOLUTE_ACCURACY).sample(); } @@ -410,8 +425,10 @@ public class RandomDataGenerator implements RandomData, Serializable { * @param shape the shape parameter of the Weibull distribution * @param scale the scale parameter of the Weibull distribution * @return random value sampled from the Weibull(shape, size) distribution + * @throws NotStrictlyPositiveException if {@code shape <= 0} or + * {@code scale <= 0}. */ - public double nextWeibull(double shape, double scale) { + public double nextWeibull(double shape, double scale) throws NotStrictlyPositiveException { return new WeibullDistribution(getRan(), shape, scale, WeibullDistribution.DEFAULT_INVERSE_ABSOLUTE_ACCURACY).sample(); } @@ -422,8 +439,10 @@ public class RandomDataGenerator implements RandomData, Serializable { * @param numberOfElements the number of elements of the ZipfDistribution * @param exponent the exponent of the ZipfDistribution * @return random value sampled from the Zipf(numberOfElements, exponent) distribution + * @exception NotStrictlyPositiveException if {@code numberOfElements <= 0} + * or {@code exponent <= 0}. */ - public int nextZipf(int numberOfElements, double exponent) { + public int nextZipf(int numberOfElements, double exponent) throws NotStrictlyPositiveException { return new ZipfDistribution(getRan(), numberOfElements, exponent).sample(); } @@ -479,8 +498,10 @@ public class RandomDataGenerator implements RandomData, Serializable { * @param numeratorDf the numerator degrees of freedom of the F distribution * @param denominatorDf the denominator degrees of freedom of the F distribution * @return random value sampled from the F(numeratorDf, denominatorDf) distribution + * @throws NotStrictlyPositiveException if + * {@code numeratorDf <= 0} or {@code denominatorDf <= 0}. */ - public double nextF(double numeratorDf, double denominatorDf) { + public double nextF(double numeratorDf, double denominatorDf) throws NotStrictlyPositiveException { return new FDistribution(getRan(), numeratorDf, denominatorDf, FDistribution.DEFAULT_INVERSE_ABSOLUTE_ACCURACY).sample(); } @@ -494,11 +515,12 @@ public class RandomDataGenerator implements RandomData, Serializable { * random double if Random.nextDouble() returns 0). This is necessary to * provide a symmetric output interval (both endpoints excluded). *

    - * - * @throws MathIllegalArgumentException if one of the bounds is infinite or - * {@code NaN} or either bound is infinite or NaN + * @throws NumberIsTooLargeException if {@code lower >= upper} + * @throws NotFiniteNumberException if one of the bounds is infinite + * @throws NotANumberException if one of the bounds is not a number */ - public double nextUniform(double lower, double upper) { + public double nextUniform(double lower, double upper) + throws NumberIsTooLargeException, NotFiniteNumberException, NotANumberException { return nextUniform(lower, upper, false); } @@ -513,23 +535,29 @@ public class RandomDataGenerator implements RandomData, Serializable { * endpoints excluded). *

    * - * @throws MathIllegalArgumentException if one of the bounds is infinite or + * @throws N if one of the bounds is infinite or * {@code NaN} + * @throws NumberIsTooLargeException if {@code lower >= upper} + * @throws NotFiniteNumberException if one of the bounds is infinite + * @throws NotANumberException if one of the bounds is not a number */ - public double nextUniform(double lower, double upper, - boolean lowerInclusive) { + public double nextUniform(double lower, double upper, boolean lowerInclusive) + throws NumberIsTooLargeException, NotFiniteNumberException, NotANumberException { if (lower >= upper) { - throw new MathIllegalArgumentException(LocalizedFormats.LOWER_BOUND_NOT_BELOW_UPPER_BOUND, + throw new NumberIsTooLargeException(LocalizedFormats.LOWER_BOUND_NOT_BELOW_UPPER_BOUND, lower, upper, false); } - if (Double.isInfinite(lower) || Double.isInfinite(upper)) { - throw new MathIllegalArgumentException(LocalizedFormats.INFINITE_BOUND); + if (Double.isInfinite(lower)) { + throw new NotFiniteNumberException(LocalizedFormats.INFINITE_BOUND, lower); + } + if (Double.isInfinite(upper)) { + throw new NotFiniteNumberException(LocalizedFormats.INFINITE_BOUND, upper); } if (Double.isNaN(lower) || Double.isNaN(upper)) { - throw new MathIllegalArgumentException(LocalizedFormats.NAN_NOT_ALLOWED); + throw new NotANumberException(); } final RandomGenerator generator = getRan(); @@ -551,10 +579,13 @@ public class RandomDataGenerator implements RandomData, Serializable { * href="http://www.maths.abdn.ac.uk/~igc/tch/mx4002/notes/node83.html"> * here. *

    + * @throws NumberIsTooLargeException if {@code k > n}. + * @throws NotStrictlyPositiveException if {@code k <= 0}. */ - public int[] nextPermutation(int n, int k) { + public int[] nextPermutation(int n, int k) + throws NumberIsTooLargeException, NotStrictlyPositiveException { if (k > n) { - throw new MathIllegalArgumentException(LocalizedFormats.PERMUTATION_EXCEEDS_N, + throw new NumberIsTooLargeException(LocalizedFormats.PERMUTATION_EXCEEDS_N, k, n, true); } if (k <= 0) { @@ -585,7 +616,7 @@ public class RandomDataGenerator implements RandomData, Serializable { * here *

    */ - public Object[] nextSample(Collection c, int k) { + public Object[] nextSample(Collection c, int k) throws NumberIsTooLargeException, NotStrictlyPositiveException { int len = c.size(); if (k > len) { @@ -720,7 +751,7 @@ public class RandomDataGenerator implements RandomData, Serializable { * @param list list to be shuffled * @param end element past which shuffling begins */ - private void shuffle(int[] list, int end) { + private void shuffle(int[] list, int end) throws NumberIsTooLargeException { int target = 0; for (int i = list.length - 1; i >= end; i--) { if (i == 0) { diff --git a/src/main/java/org/apache/commons/math3/random/RandomDataImpl.java b/src/main/java/org/apache/commons/math3/random/RandomDataImpl.java index 548d251fb..2ba8a9fcf 100644 --- a/src/main/java/org/apache/commons/math3/random/RandomDataImpl.java +++ b/src/main/java/org/apache/commons/math3/random/RandomDataImpl.java @@ -24,6 +24,13 @@ import java.util.Collection; import org.apache.commons.math3.distribution.IntegerDistribution; import org.apache.commons.math3.distribution.RealDistribution; +import org.apache.commons.math3.exception.NotANumberException; +import org.apache.commons.math3.exception.NotFiniteNumberException; +import org.apache.commons.math3.exception.NotPositiveException; +import org.apache.commons.math3.exception.NotStrictlyPositiveException; +import org.apache.commons.math3.exception.MathIllegalArgumentException; +import org.apache.commons.math3.exception.NumberIsTooLargeException; +import org.apache.commons.math3.exception.OutOfRangeException; /** * Generates random deviates and other random data using a {@link RandomGenerator} @@ -135,17 +142,17 @@ public class RandomDataImpl implements RandomData, Serializable { * @return the random string. * @throws NotStrictlyPositiveException if {@code len <= 0}. */ - public String nextHexString(int len) { + public String nextHexString(int len) throws NotStrictlyPositiveException { return delegate.nextHexString(len); } /** {@inheritDoc} */ - public int nextInt(int lower, int upper) { + public int nextInt(int lower, int upper) throws NumberIsTooLargeException { return delegate.nextInt(lower, upper); } /** {@inheritDoc} */ - public long nextLong(long lower, long upper) { + public long nextLong(long lower, long upper) throws NumberIsTooLargeException { return delegate.nextLong(lower, upper); } @@ -165,17 +172,17 @@ public class RandomDataImpl implements RandomData, Serializable { * *

    */ - public String nextSecureHexString(int len) { + public String nextSecureHexString(int len) throws NotStrictlyPositiveException { return delegate.nextSecureHexString(len); } /** {@inheritDoc} */ - public int nextSecureInt(int lower, int upper) { + public int nextSecureInt(int lower, int upper) throws NumberIsTooLargeException { return delegate.nextSecureInt(lower, upper); } /** {@inheritDoc} */ - public long nextSecureLong(long lower, long upper) { + public long nextSecureLong(long lower, long upper) throws NumberIsTooLargeException { return delegate.nextSecureLong(lower,upper); } @@ -192,12 +199,12 @@ public class RandomDataImpl implements RandomData, Serializable { * Devroye, Luc. (1981).The Computer Generation of Poisson Random Variables * Computing vol. 26 pp. 197-207.

    */ - public long nextPoisson(double mean) { + public long nextPoisson(double mean) throws NotStrictlyPositiveException { return delegate.nextPoisson(mean); } /** {@inheritDoc} */ - public double nextGaussian(double mu, double sigma) { + public double nextGaussian(double mu, double sigma) throws NotStrictlyPositiveException { return delegate.nextGaussian(mu,sigma); } @@ -212,7 +219,7 @@ public class RandomDataImpl implements RandomData, Serializable { * Communications of the ACM, 15, 873-882. *

    */ - public double nextExponential(double mean) { + public double nextExponential(double mean) throws NotStrictlyPositiveException { return delegate.nextExponential(mean); } @@ -225,11 +232,9 @@ public class RandomDataImpl implements RandomData, Serializable { * random double if Random.nextDouble() returns 0). This is necessary to * provide a symmetric output interval (both endpoints excluded). *

    - * - * @throws MathIllegalArgumentException if one of the bounds is infinite or - * {@code NaN} or either bound is infinite or NaN */ - public double nextUniform(double lower, double upper) { + public double nextUniform(double lower, double upper) + throws NumberIsTooLargeException, NotFiniteNumberException, NotANumberException { return delegate.nextUniform(lower, upper); } @@ -243,13 +248,10 @@ public class RandomDataImpl implements RandomData, Serializable { * This is necessary to provide a symmetric output interval (both * endpoints excluded). *

    - * - * @throws MathIllegalArgumentException if one of the bounds is infinite or - * {@code NaN} * @since 3.0 */ - public double nextUniform(double lower, double upper, - boolean lowerInclusive) { + public double nextUniform(double lower, double upper, boolean lowerInclusive) + throws NumberIsTooLargeException, NotFiniteNumberException, NotANumberException { return delegate.nextUniform(lower, upper, lowerInclusive); } @@ -316,9 +318,11 @@ public class RandomDataImpl implements RandomData, Serializable { * @param numeratorDf the numerator degrees of freedom of the F distribution * @param denominatorDf the denominator degrees of freedom of the F distribution * @return random value sampled from the F(numeratorDf, denominatorDf) distribution + * @throws NotStrictlyPositiveException if + * {@code numeratorDf <= 0} or {@code denominatorDf <= 0}. * @since 2.2 */ - public double nextF(double numeratorDf, double denominatorDf) { + public double nextF(double numeratorDf, double denominatorDf) throws NotStrictlyPositiveException { return delegate.nextF(numeratorDf, denominatorDf); } @@ -341,9 +345,11 @@ public class RandomDataImpl implements RandomData, Serializable { * @param shape the median of the Gamma distribution * @param scale the scale parameter of the Gamma distribution * @return random value sampled from the Gamma(shape, scale) distribution + * @throws NotStrictlyPositiveException if {@code shape <= 0} or + * {@code scale <= 0}. * @since 2.2 */ - public double nextGamma(double shape, double scale) { + public double nextGamma(double shape, double scale) throws NotStrictlyPositiveException { return delegate.nextGamma(shape, scale); } @@ -356,9 +362,14 @@ public class RandomDataImpl implements RandomData, Serializable { * @param numberOfSuccesses number of successes in the population of the Hypergeometric distribution * @param sampleSize the sample size of the Hypergeometric distribution * @return random value sampled from the Hypergeometric(numberOfSuccesses, sampleSize) distribution + * @throws NumberIsTooLargeException if {@code numberOfSuccesses > populationSize}, + * or {@code sampleSize > populationSize}. + * @throws NotStrictlyPositiveException if {@code populationSize <= 0}. + * @throws NotPositiveException if {@code numberOfSuccesses < 0}. * @since 2.2 */ - public int nextHypergeometric(int populationSize, int numberOfSuccesses, int sampleSize) { + public int nextHypergeometric(int populationSize, int numberOfSuccesses, int sampleSize) + throws NotPositiveException, NotStrictlyPositiveException, NumberIsTooLargeException { return delegate.nextHypergeometric(populationSize, numberOfSuccesses, sampleSize); } @@ -371,8 +382,12 @@ public class RandomDataImpl implements RandomData, Serializable { * @param p the probability of success of the Pascal distribution * @return random value sampled from the Pascal(r, p) distribution * @since 2.2 + * @throws NotStrictlyPositiveException if the number of successes is not positive + * @throws OutOfRangeException if the probability of success is not in the + * range {@code [0, 1]}. */ - public int nextPascal(int r, double p) { + public int nextPascal(int r, double p) + throws NotStrictlyPositiveException, OutOfRangeException { return delegate.nextPascal(r, p); } @@ -384,8 +399,9 @@ public class RandomDataImpl implements RandomData, Serializable { * @param df the degrees of freedom of the T distribution * @return random value from the T(df) distribution * @since 2.2 + * @throws NotStrictlyPositiveException if {@code df <= 0} */ - public double nextT(double df) { + public double nextT(double df) throws NotStrictlyPositiveException { return delegate.nextT(df); } @@ -398,8 +414,10 @@ public class RandomDataImpl implements RandomData, Serializable { * @param scale the scale parameter of the Weibull distribution * @return random value sampled from the Weibull(shape, size) distribution * @since 2.2 + * @throws NotStrictlyPositiveException if {@code shape <= 0} or + * {@code scale <= 0}. */ - public double nextWeibull(double shape, double scale) { + public double nextWeibull(double shape, double scale) throws NotStrictlyPositiveException { return delegate.nextWeibull(shape, scale); } @@ -412,8 +430,10 @@ public class RandomDataImpl implements RandomData, Serializable { * @param exponent the exponent of the ZipfDistribution * @return random value sampled from the Zipf(numberOfElements, exponent) distribution * @since 2.2 + * @exception NotStrictlyPositiveException if {@code numberOfElements <= 0} + * or {@code exponent <= 0}. */ - public int nextZipf(int numberOfElements, double exponent) { + public int nextZipf(int numberOfElements, double exponent) throws NotStrictlyPositiveException { return delegate.nextZipf(numberOfElements, exponent); } @@ -497,7 +517,8 @@ public class RandomDataImpl implements RandomData, Serializable { * here. *

    */ - public int[] nextPermutation(int n, int k) { + public int[] nextPermutation(int n, int k) + throws NotStrictlyPositiveException, NumberIsTooLargeException { return delegate.nextPermutation(n, k); } @@ -514,7 +535,8 @@ public class RandomDataImpl implements RandomData, Serializable { * here *

    */ - public Object[] nextSample(Collection c, int k) { + public Object[] nextSample(Collection c, int k) + throws NotStrictlyPositiveException, NumberIsTooLargeException { return delegate.nextSample(c, k); } @@ -524,10 +546,12 @@ public class RandomDataImpl implements RandomData, Serializable { * * @param distribution Continuous distribution to generate a random value from * @return a random value sampled from the given distribution + * @throws MathIllegalArgumentException if the underlynig distribution throws one * @since 2.2 * @deprecated use the distribution's sample() method */ - public double nextInversionDeviate(RealDistribution distribution) { + public double nextInversionDeviate(RealDistribution distribution) + throws MathIllegalArgumentException { return distribution.inverseCumulativeProbability(nextUniform(0, 1)); } @@ -538,10 +562,12 @@ public class RandomDataImpl implements RandomData, Serializable { * * @param distribution Integer distribution to generate a random value from * @return a random value sampled from the given distribution + * @throws MathIllegalArgumentException if the underlynig distribution throws one * @since 2.2 * @deprecated use the distribution's sample() method */ - public int nextInversionDeviate(IntegerDistribution distribution) { + public int nextInversionDeviate(IntegerDistribution distribution) + throws MathIllegalArgumentException { return distribution.inverseCumulativeProbability(nextUniform(0, 1)); } diff --git a/src/main/java/org/apache/commons/math3/random/StableRandomGenerator.java b/src/main/java/org/apache/commons/math3/random/StableRandomGenerator.java index 7effbc117..7f106062f 100644 --- a/src/main/java/org/apache/commons/math3/random/StableRandomGenerator.java +++ b/src/main/java/org/apache/commons/math3/random/StableRandomGenerator.java @@ -51,9 +51,13 @@ public class StableRandomGenerator implements NormalizedRandomGenerator { * @param generator underlying random generator to use * @param alpha Stability parameter. Must be in range (0, 2] * @param beta Skewness parameter. Must be in range [-1, 1] + * @throws NullArgumentException if generator is null + * @throws OutOfRangeException if {@code alpha <= 0} or {@code alpha > 2} + * or {@code beta < -1} or {@code beta > 1} */ - public StableRandomGenerator(final RandomGenerator generator, double alpha, - double beta) { + public StableRandomGenerator(final RandomGenerator generator, + final double alpha, final double beta) + throws NullArgumentException, OutOfRangeException { if (generator == null) { throw new NullArgumentException(); } diff --git a/src/main/java/org/apache/commons/math3/random/ValueServer.java b/src/main/java/org/apache/commons/math3/random/ValueServer.java index d3ca8aff7..e013b5d2e 100644 --- a/src/main/java/org/apache/commons/math3/random/ValueServer.java +++ b/src/main/java/org/apache/commons/math3/random/ValueServer.java @@ -22,7 +22,10 @@ import java.io.InputStreamReader; import java.net.MalformedURLException; import java.net.URL; +import org.apache.commons.math3.exception.MathIllegalArgumentException; import org.apache.commons.math3.exception.MathIllegalStateException; +import org.apache.commons.math3.exception.NullArgumentException; +import org.apache.commons.math3.exception.ZeroException; import org.apache.commons.math3.exception.util.LocalizedFormats; /** @@ -111,8 +114,10 @@ public class ValueServer { * * @return generated value * @throws IOException in REPLAY_MODE if a file I/O error occurs + * @throws MathIllegalStateException if mode is not recognized + * @throws MathIllegalArgumentException if the underlying random generator thwrows one */ - public double getNext() throws IOException { + public double getNext() throws IOException, MathIllegalStateException, MathIllegalArgumentException { switch (mode) { case DIGEST_MODE: return getNextDigest(); case REPLAY_MODE: return getNextReplay(); @@ -134,8 +139,11 @@ public class ValueServer { * * @param values array to be filled * @throws IOException in REPLAY_MODE if a file I/O error occurs + * @throws MathIllegalStateException if mode is not recognized + * @throws MathIllegalArgumentException if the underlying random generator thwrows one */ - public void fill(double[] values) throws IOException { + public void fill(double[] values) + throws IOException, MathIllegalStateException, MathIllegalArgumentException { for (int i = 0; i < values.length; i++) { values[i] = getNext(); } @@ -148,8 +156,11 @@ public class ValueServer { * @param length length of output array * @return array of generated values * @throws IOException in REPLAY_MODE if a file I/O error occurs + * @throws MathIllegalStateException if mode is not recognized + * @throws MathIllegalArgumentException if the underlying random generator thwrows one */ - public double[] fill(int length) throws IOException { + public double[] fill(int length) + throws IOException, MathIllegalStateException, MathIllegalArgumentException { double[] out = new double[length]; for (int i = 0; i < length; i++) { out[i] = getNext(); @@ -168,8 +179,10 @@ public class ValueServer { * with mode = DIGEST_MODE

    * * @throws IOException if an I/O error occurs reading the input file + * @throws NullArgumentException + * @throws ZeroException if URL contains no data */ - public void computeDistribution() throws IOException { + public void computeDistribution() throws IOException, ZeroException, NullArgumentException { computeDistribution(EmpiricalDistribution.DEFAULT_BIN_COUNT); } @@ -185,10 +198,11 @@ public class ValueServer { * * @param binCount the number of bins used in computing the empirical * distribution + * @throws NullArgumentException * @throws IOException if an error occurs reading the input file + * @throws ZeroException if URL contains no data */ - public void computeDistribution(int binCount) - throws IOException { + public void computeDistribution(int binCount) throws NullArgumentException, IOException, ZeroException { empiricalDistribution = new EmpiricalDistribution(binCount, randomData); empiricalDistribution.load(valuesFileURL); mu = empiricalDistribution.getSampleStats().getMean(); @@ -348,8 +362,9 @@ public class ValueServer { * IllegalStateException will be thrown

    * * @return next random value from the empirical distribution digest + * @throws MathIllegalStateException if digest has not been initialized */ - private double getNextDigest() { + private double getNextDigest() throws MathIllegalStateException { if ((empiricalDistribution == null) || (empiricalDistribution.getBinStats().size() == 0)) { throw new MathIllegalStateException(LocalizedFormats.DIGEST_NOT_INITIALIZED); @@ -372,10 +387,11 @@ public class ValueServer { * * @return next value from the replay file * @throws IOException if there is a problem reading from the file + * @throws MathIllegalStateException if URL contains no data * @throws NumberFormatException if an invalid numeric string is * encountered in the file */ - private double getNextReplay() throws IOException { + private double getNextReplay() throws IOException, MathIllegalStateException { String str = null; if (filePointer == null) { resetReplayFile(); @@ -396,8 +412,9 @@ public class ValueServer { * Gets a uniformly distributed random value with mean = mu. * * @return random uniform value + * @throws MathIllegalArgumentException if the underlying random generator thwrows one */ - private double getNextUniform() { + private double getNextUniform() throws MathIllegalArgumentException { return randomData.nextUniform(0, 2 * mu); } @@ -405,8 +422,9 @@ public class ValueServer { * Gets an exponentially distributed random value with mean = mu. * * @return random exponential value + * @throws MathIllegalArgumentException if the underlying random generator thwrows one */ - private double getNextExponential() { + private double getNextExponential() throws MathIllegalArgumentException { return randomData.nextExponential(mu); } @@ -415,8 +433,9 @@ public class ValueServer { * and standard deviation = sigma. * * @return random Gaussian value + * @throws MathIllegalArgumentException if the underlying random generator thwrows one */ - private double getNextGaussian() { + private double getNextGaussian() throws MathIllegalArgumentException { return randomData.nextGaussian(mu, sigma); }