    001    /*
    002     * Licensed to the Apache Software Foundation (ASF) under one or more
    003     * contributor license agreements.  See the NOTICE file distributed with
    004     * this work for additional information regarding copyright ownership.
    005     * The ASF licenses this file to You under the Apache License, Version 2.0
    006     * (the "License"); you may not use this file except in compliance with
    007     * the License.  You may obtain a copy of the License at
    008     *
    009     *      http://www.apache.org/licenses/LICENSE-2.0
    010     *
    011     * Unless required by applicable law or agreed to in writing, software
    012     * distributed under the License is distributed on an "AS IS" BASIS,
    013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014     * See the License for the specific language governing permissions and
    015     * limitations under the License.
    016     */
    017
    018    package org.apache.commons.math3.random;
    019    import java.util.Collection;
    020
    021    import org.apache.commons.math3.exception.NotANumberException;
    022    import org.apache.commons.math3.exception.NotFiniteNumberException;
    023    import org.apache.commons.math3.exception.NotStrictlyPositiveException;
    024    import org.apache.commons.math3.exception.NumberIsTooLargeException;
    025
    026    /**
    027     * Random data generation utilities.
    028     * @deprecated to be removed in 4.0.  Use {@link RandomDataGenerator} directly
    029     * @version $Id: RandomData.java 1416643 2012-12-03 19:37:14Z tn $
    030     */
    031    public interface RandomData {
    032        /**
    033         * Generates a random string of hex characters of length {@code len}.
    034         * <p>
    035         * The generated string will be random, but not cryptographically
    036         * secure. To generate cryptographically secure strings, use
    037         * {@link #nextSecureHexString(int)}.
    038         * </p>
    039         *
    040         * @param len the length of the string to be generated
    041         * @return a random string of hex characters of length {@code len}
    042         * @throws NotStrictlyPositiveException
    043         * if {@code len <= 0}
    044         */
    045        String nextHexString(int len) throws NotStrictlyPositiveException;
    046
    047        /**
    048         * Generates a uniformly distributed random integer between {@code lower}
    049         * and {@code upper} (endpoints included).
    050         * <p>
    051         * The generated integer will be random, but not cryptographically secure.
    052         * To generate cryptographically secure integer sequences, use
    053         * {@link #nextSecureInt(int, int)}.
    054         * </p>
    055         *
    056         * @param lower lower bound for generated integer
    057         * @param upper upper bound for generated integer
    058         * @return a random integer greater than or equal to {@code lower}
    059         * and less than or equal to {@code upper}
    060         * @throws NumberIsTooLargeException if {@code lower >= upper}
    061         */
    062        int nextInt(int lower, int upper) throws NumberIsTooLargeException;
    063
    064        /**
    065         * Generates a uniformly distributed random long integer between
    066         * {@code lower} and {@code upper} (endpoints included).
    067         * <p>
    068         * The generated long integer values will be random, but not
    069         * cryptographically secure. To generate cryptographically secure sequences
    070         * of longs, use {@link #nextSecureLong(long, long)}.
    071         * </p>
    072         *
    073         * @param lower lower bound for generated long integer
    074         * @param upper upper bound for generated long integer
    075         * @return a random long integer greater than or equal to {@code lower} and
    076         * less than or equal to {@code upper}
    077         * @throws NumberIsTooLargeException if {@code lower >= upper}
    078         */
    079        long nextLong(long lower, long upper) throws NumberIsTooLargeException;
    080
    081        /**
    082         * Generates a random string of hex characters from a secure random
    083         * sequence.
    084         * <p>
    085         * If cryptographic security is not required, use
    086         * {@link #nextHexString(int)}.
    087         * </p>
    088         *
    089         * @param len the length of the string to be generated
    090         * @return a random string of hex characters of length {@code len}
    091         * @throws NotStrictlyPositiveException if {@code len <= 0}
    092         */
    093        String nextSecureHexString(int len) throws NotStrictlyPositiveException;
    094
    095        /**
    096         * Generates a uniformly distributed random integer between {@code lower}
    097         * and {@code upper} (endpoints included) from a secure random sequence.
    098         * <p>
    099         * Sequences of integers generated using this method will be
    100         * cryptographically secure. If cryptographic security is not required,
    101         * {@link #nextInt(int, int)} should be used instead of this method.</p>
    102         * <p>
    103         * <strong>Definition</strong>:
    104         * <a href="http://en.wikipedia.org/wiki/Cryptographically_secure_pseudo-random_number_generator">
    105         * Secure Random Sequence</a></p>
    106         *
    107         * @param lower lower bound for generated integer
    108         * @param upper upper bound for generated integer
    109         * @return a random integer greater than or equal to {@code lower} and less
    110         * than or equal to {@code upper}.
    111         * @throws NumberIsTooLargeException if {@code lower >= upper}.
    112         */
    113        int nextSecureInt(int lower, int upper) throws NumberIsTooLargeException;
    114
    115        /**
    116         * Generates a uniformly distributed random long integer between
    117         * {@code lower} and {@code upper} (endpoints included) from a secure random
    118         * sequence.
    119         * <p>
    120         * Sequences of long values generated using this method will be
    121         * cryptographically secure. If cryptographic security is not required,
    122         * {@link #nextLong(long, long)} should be used instead of this method.</p>
    123         * <p>
    124         * <strong>Definition</strong>:
    125         * <a href="http://en.wikipedia.org/wiki/Cryptographically_secure_pseudo-random_number_generator">
    126         * Secure Random Sequence</a></p>
    127         *
    128         * @param lower lower bound for generated integer
    129         * @param upper upper bound for generated integer
    130         * @return a random long integer greater than or equal to {@code lower} and
    131         * less than or equal to {@code upper}.
    132         * @throws NumberIsTooLargeException if {@code lower >= upper}.
    133         */
    134        long nextSecureLong(long lower, long upper) throws NumberIsTooLargeException;
    135
    136        /**
    137         * Generates a random value from the Poisson distribution with the given
    138         * mean.
    139         * <p>
    140         * <strong>Definition</strong>:
    141         * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda366j.htm">
    142         * Poisson Distribution</a></p>
    143         *
    144         * @param mean the mean of the Poisson distribution
    145         * @return a random value following the specified Poisson distribution
    146         * @throws NotStrictlyPositiveException if {@code mean <= 0}.
    147         */
    148        long nextPoisson(double mean) throws NotStrictlyPositiveException;
    149
    150        /**
    151         * Generates a random value from the Normal (or Gaussian) distribution with
    152         * specified mean and standard deviation.
    153         * <p>
    154         * <strong>Definition</strong>:
    155         * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3661.htm">
    156         * Normal Distribution</a></p>
    157         *
    158         * @param mu the mean of the distribution
    159         * @param sigma the standard deviation of the distribution
    160         * @return a random value following the specified Gaussian distribution
    161         * @throws NotStrictlyPositiveException if {@code sigma <= 0}.
    162         */
    163        double nextGaussian(double mu, double sigma) throws NotStrictlyPositiveException;
    164
    165        /**
    166         * Generates a random value from the exponential distribution
    167         * with specified mean.
    168         * <p>
    169         * <strong>Definition</strong>:
    170         * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3667.htm">
    171         * Exponential Distribution</a></p>
    172         *
    173         * @param mean the mean of the distribution
    174         * @return a random value following the specified exponential distribution
    175         * @throws NotStrictlyPositiveException if {@code mean <= 0}.
    176         */
    177        double nextExponential(double mean) throws NotStrictlyPositiveException;
    178
    179        /**
    180         * Generates a uniformly distributed random value from the open interval
    181         * {@code (lower, upper)} (i.e., endpoints excluded).
    182         * <p>
    183         * <strong>Definition</strong>:
    184         * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3662.htm">
    185         * Uniform Distribution</a> {@code lower} and {@code upper - lower} are the
    186         * <a href = "http://www.itl.nist.gov/div898/handbook/eda/section3/eda364.htm">
    187         * location and scale parameters</a>, respectively.</p>
    188         *
    189         * @param lower the exclusive lower bound of the support
    190         * @param upper the exclusive upper bound of the support
    191         * @return a uniformly distributed random value between lower and upper
    192         * (exclusive)
    193         * @throws NumberIsTooLargeException if {@code lower >= upper}
    194         * @throws NotFiniteNumberException if one of the bounds is infinite
    195         * @throws NotANumberException if one of the bounds is NaN
    196         */
    197        double nextUniform(double lower, double upper)
    198            throws NumberIsTooLargeException, NotFiniteNumberException, NotANumberException;
    199
    200        /**
    201         * Generates a uniformly distributed random value from the interval
    202         * {@code (lower, upper)} or the interval {@code [lower, upper)}. The lower
    203         * bound is thus optionally included, while the upper bound is always
    204         * excluded.
    205         * <p>
    206         * <strong>Definition</strong>:
    207         * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3662.htm">
    208         * Uniform Distribution</a> {@code lower} and {@code upper - lower} are the
    209         * <a href = "http://www.itl.nist.gov/div898/handbook/eda/section3/eda364.htm">
    210         * location and scale parameters</a>, respectively.</p>
    211         *
    212         * @param lower the lower bound of the support
    213         * @param upper the exclusive upper bound of the support
    214         * @param lowerInclusive {@code true} if the lower bound is inclusive
    215         * @return uniformly distributed random value in the {@code (lower, upper)}
    216         * interval, if {@code lowerInclusive} is {@code false}, or in the
    217         * {@code [lower, upper)} interval, if {@code lowerInclusive} is
    218         * {@code true}
    219         * @throws NumberIsTooLargeException if {@code lower >= upper}
    220         * @throws NotFiniteNumberException if one of the bounds is infinite
    221         * @throws NotANumberException if one of the bounds is NaN
    222         */
    223        double nextUniform(double lower, double upper, boolean lowerInclusive)
    224            throws NumberIsTooLargeException, NotFiniteNumberException, NotANumberException;
    225
    226        /**
    227         * Generates an integer array of length {@code k} whose entries are selected
    228         * randomly, without repetition, from the integers {@code 0, ..., n - 1}
    229         * (inclusive).
    230         * <p>
    231         * Generated arrays represent permutations of {@code n} taken {@code k} at a
    232         * time.</p>
    233         *
    234         * @param n the domain of the permutation
    235         * @param k the size of the permutation
    236         * @return a random {@code k}-permutation of {@code n}, as an array of
    237         * integers
    238         * @throws NumberIsTooLargeException if {@code k > n}.
    239         * @throws NotStrictlyPositiveException if {@code k <= 0}.
    240         */
    241        int[] nextPermutation(int n, int k)
    242            throws NumberIsTooLargeException, NotStrictlyPositiveException;
    243
    244        /**
    245         * Returns an array of {@code k} objects selected randomly from the
    246         * Collection {@code c}.
    247         * <p>
    248         * Sampling from {@code c} is without replacement; but if {@code c} contains
    249         * identical objects, the sample may include repeats.  If all elements of
    250         * {@code c} are distinct, the resulting object array represents a
    251         * <a href="http://rkb.home.cern.ch/rkb/AN16pp/node250.html#SECTION0002500000000000000000">
    252         * Simple Random Sample</a> of size {@code k} from the elements of
    253         * {@code c}.</p>
    254         *
    255         * @param c the collection to be sampled
    256         * @param k the size of the sample
    257         * @return a random sample of {@code k} elements from {@code c}
    258         * @throws NumberIsTooLargeException if {@code k > c.size()}.
    259         * @throws NotStrictlyPositiveException if {@code k <= 0}.
    260         */
    261        Object[] nextSample(Collection<?> c, int k)
    262            throws NumberIsTooLargeException, NotStrictlyPositiveException;
    263
    264    }