    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.math.random;
    019    import java.util.Collection;
    020
    021    /**
    022     * Random data generation utilities.
    023     * @version $Revision: 780975 $ $Date: 2009-06-02 11:05:37 +0200 (mar. 02 juin 2009) $
    024     */
    025    public interface RandomData {
    026        /**
    027         * Generates a random string of hex characters of length
    028         * <code>len</code>.
    029         * <p>
    030         * The generated string will be random, but not cryptographically
    031         * secure. To generate cryptographically secure strings, use
    032         * <code>nextSecureHexString</code></p>
    033         * <p>
    034         * <strong>Preconditions</strong>:<ul>
    035         * <li><code>len > 0</code> (otherwise an IllegalArgumentException
    036         *     is thrown.)</li>
    037         * </ul></p>
    038         *
    039         * @param len the length of the string to be generated
    040         * @return random string of hex characters of length <code>len</code>
    041         */
    042        String nextHexString(int len);
    043
    044        /**
    045         * Generates a uniformly distributed random integer between
    046         * <code>lower</code> and <code>upper</code> (endpoints included).
    047         * <p>
    048         * The generated integer will be random, but not cryptographically secure.
    049         * To generate cryptographically secure integer sequences, use
    050         * <code>nextSecureInt</code>.</p>
    051         * <p>
    052         * <strong>Preconditions</strong>:<ul>
    053         * <li><code>lower < upper</code> (otherwise an IllegalArgumentException
    054         *     is thrown.)</li>
    055         * </ul></p>
    056         *
    057         * @param lower lower bound for generated integer
    058         * @param upper upper bound for generated integer
    059         * @return a random integer greater than or equal to <code>lower</code>
    060         * and less than or equal to <code>upper</code>.
    061         */
    062        int nextInt(int lower, int upper);
    063
    064        /**
    065         * Generates a uniformly distributed random long integer between
    066         * <code>lower</code> and <code>upper</code> (endpoints included).
    067         * <p>
    068         * The generated long integer values will be random, but not
    069         * cryptographically secure.
    070         * To generate cryptographically secure sequences of longs, use
    071         * <code>nextSecureLong</code></p>
    072         * <p>
    073         * <strong>Preconditions</strong>:<ul>
    074         * <li><code>lower < upper</code> (otherwise an IllegalArgumentException
    075         *     is thrown.)</li>
    076         * </ul></p>
    077         *
    078         * @param lower lower bound for generated integer
    079         * @param upper upper bound for generated integer
    080         * @return a random integer greater than or equal to <code>lower</code>
    081         * and less than or equal to <code>upper</code>.
    082         */
    083        long nextLong(long lower, long upper);
    084
    085        /**
    086         * Generates a random string of hex characters from a secure random
    087         * sequence.
    088         * <p>
    089         * If cryptographic security is not required,
    090         * use <code>nextHexString()</code>.</p>
    091         * <p>
    092         * <strong>Preconditions</strong>:<ul>
    093         * <li><code>len > 0</code> (otherwise an IllegalArgumentException
    094         *     is thrown.)</li>
    095         * </ul></p>
    096         * @param len length of return string
    097         * @return the random hex string
    098         */
    099        String nextSecureHexString(int len);
    100
    101        /**
    102         * Generates a uniformly distributed random integer between
    103         * <code>lower</code> and <code>upper</code> (endpoints included)
    104         * from a secure random sequence.
    105         * <p>
    106         * Sequences of integers generated using this method will be
    107         * cryptographically secure. If cryptographic security is not required,
    108         * <code>nextInt</code> should be used instead of this method.</p>
    109         * <p>
    110         * <strong>Definition</strong>:
    111         * <a href="http://en.wikipedia.org/wiki/Cryptographically_secure_pseudo-random_number_generator">
    112         * Secure Random Sequence</a></p>
    113         * <p>
    114         * <strong>Preconditions</strong>:<ul>
    115         * <li><code>lower < upper</code> (otherwise an IllegalArgumentException
    116         *     is thrown.)</li>
    117         * </ul></p>
    118         *
    119         * @param lower lower bound for generated integer
    120         * @param upper upper bound for generated integer
    121         * @return a random integer greater than or equal to <code>lower</code>
    122         * and less than or equal to <code>upper</code>.
    123         */
    124        int nextSecureInt(int lower, int upper);
    125
    126        /**
    127         * Generates a random long integer between <code>lower</code>
    128         * and <code>upper</code> (endpoints included).
    129         * <p>
    130         * Sequences of long values generated using this method will be
    131         * cryptographically secure. If cryptographic security is not required,
    132         * <code>nextLong</code> should be used instead of this method.</p>
    133         * <p>
    134         * <strong>Definition</strong>:
    135         * <a href="http://en.wikipedia.org/wiki/Cryptographically_secure_pseudo-random_number_generator">
    136         * Secure Random Sequence</a></p>
    137         * <p>
    138         * <strong>Preconditions</strong>:<ul>
    139         * <li><code>lower < upper</code> (otherwise an IllegalArgumentException
    140         *     is thrown.)</li>
    141         * </ul></p>
    142         *
    143         * @param lower lower bound for generated integer
    144         * @param upper upper bound for generated integer
    145         * @return a long integer greater than or equal to <code>lower</code>
    146         * and less than or equal to <code>upper</code>.
    147         */
    148        long nextSecureLong(long lower, long upper);
    149
    150        /**
    151         * Generates a random value from the Poisson distribution with
    152         * the given mean.
    153         * <p>
    154         * <strong>Definition</strong>:
    155         * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda366j.htm">
    156         * Poisson Distribution</a></p>
    157         * <p>
    158         * <strong>Preconditions</strong>: <ul>
    159         * <li>The specified mean <i>must</i> be positive (otherwise an
    160         *     IllegalArgumentException is thrown.)</li>
    161         * </ul></p>
    162         * @param mean Mean of the distribution
    163         * @return poisson deviate with the specified mean
    164         */
    165        long nextPoisson(double mean);
    166
    167        /**
    168         * Generates a random value from the
    169         * Normal (or Gaussian) distribution with the given mean
    170         * and standard deviation.
    171         * <p>
    172         * <strong>Definition</strong>:
    173         * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3661.htm">
    174         * Normal Distribution</a></p>
    175         * <p>
    176         * <strong>Preconditions</strong>: <ul>
    177         * <li><code>sigma > 0</code> (otherwise an IllegalArgumentException
    178         *     is thrown.)</li>
    179         * </ul></p>
    180         * @param mu Mean of the distribution
    181         * @param sigma Standard deviation of the distribution
    182         * @return random value from Gaussian distribution with mean = mu,
    183         * standard deviation = sigma
    184         */
    185        double nextGaussian(double mu, double sigma);
    186
    187        /**
    188         * Generates a random value from the exponential distribution
    189         * with expected value = <code>mean</code>.
    190         * <p>
    191         * <strong>Definition</strong>:
    192         * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3667.htm">
    193         * Exponential Distribution</a></p>
    194         * <p>
    195         * <strong>Preconditions</strong>: <ul>
    196         * <li><code>mu >= 0</code> (otherwise an IllegalArgumentException
    197         *     is thrown.)</li>
    198         * </ul></p>
    199         * @param mean Mean of the distribution
    200         * @return random value from exponential distribution
    201         */
    202        double nextExponential(double mean);
    203
    204        /**
    205         * Generates a uniformly distributed random value from the open interval
    206         * (<code>lower</code>,<code>upper</code>) (i.e., endpoints excluded).
    207         * <p>
    208         * <strong>Definition</strong>:
    209         * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3662.htm">
    210         * Uniform Distribution</a> <code>lower</code> and
    211         * <code>upper - lower</code> are the
    212         * <a href = "http://www.itl.nist.gov/div898/handbook/eda/section3/eda364.htm">
    213         * location and scale parameters</a>, respectively.</p>
    214         * <p>
    215         * <strong>Preconditions</strong>:<ul>
    216         * <li><code>lower < upper</code> (otherwise an IllegalArgumentException
    217         *     is thrown.)</li>
    218         * </ul></p>
    219         *
    220         * @param lower lower endpoint of the interval of support
    221         * @param upper upper endpoint of the interval of support
    222         * @return uniformly distributed random value between lower
    223         * and upper (exclusive)
    224         */
    225        double nextUniform(double lower, double upper);
    226
    227        /**
    228         * Generates an integer array of length <code>k</code> whose entries
    229         * are selected randomly, without repetition, from the integers <code>
    230         * 0 through n-1</code> (inclusive).
    231         * <p>
    232         * Generated arrays represent permutations
    233         * of <code>n</code> taken <code>k</code> at a time.</p>
    234         * <p>
    235         * <strong>Preconditions:</strong><ul>
    236         * <li> <code>k <= n</code></li>
    237         * <li> <code>n > 0</code> </li>
    238         * </ul>
    239         * If the preconditions are not met, an IllegalArgumentException is
    240         * thrown.</p>
    241         *
    242         * @param n domain of the permutation
    243         * @param k size of the permutation
    244         * @return random k-permutation of n
    245         */
    246        int[] nextPermutation(int n, int k);
    247
    248        /**
    249         * Returns an array of <code>k</code> objects selected randomly
    250         * from the Collection <code>c</code>.
    251         * <p>
    252         * Sampling from <code>c</code>
    253         * is without replacement; but if <code>c</code> contains identical
    254         * objects, the sample may include repeats.  If all elements of <code>
    255         * c</code> are distinct, the resulting object array represents a
    256         * <a href="http://rkb.home.cern.ch/rkb/AN16pp/node250.html#SECTION0002500000000000000000">
    257         * Simple Random Sample</a> of size
    258         * <code>k</code> from the elements of <code>c</code>.</p>
    259         * <p>
    260         * <strong>Preconditions:</strong><ul>
    261         * <li> k must be less than or equal to the size of c </li>
    262         * <li> c must not be empty </li>
    263         * </ul>
    264         * If the preconditions are not met, an IllegalArgumentException is
    265         * thrown.</p>
    266         *
    267         * @param c collection to be sampled
    268         * @param k size of the sample
    269         * @return random sample of k elements from c
    270         */
    271        Object[] nextSample(Collection<?> c, int k);
    272    }