View Javadoc

    1   /*
    2    * Copyright 2003-2004 The Apache Software Foundation.
    3    *
    4    * Licensed under the Apache License, Version 2.0 (the "License");
    5    * you may not use this file except in compliance with the License.
    6    * You may obtain a copy of the License at
    7    *
    8    *      http://www.apache.org/licenses/LICENSE-2.0
    9    *
    10   * Unless required by applicable law or agreed to in writing, software
    11   * distributed under the License is distributed on an "AS IS" BASIS,
    12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13   * See the License for the specific language governing permissions and
    14   * limitations under the License.
    15   */
    16
    17  package org.apache.commons.math.random;
    18  import java.util.Collection;
    19
    20  /***
    21   * Random data generation utilities.
    22   * @version $Revision: 355770 $ $Date: 2005-12-10 12:48:57 -0700 (Sat, 10 Dec 2005) $
    23   */
    24  public interface RandomData {
    25      /***
    26       * Generates a random string of hex characters of length
    27       * <code>len</code>.
    28       * <p>
    29       * The generated string will be random, but not cryptographically
    30       * secure. To generate cryptographically secure strings, use
    31       * <code>nextSecureHexString</code>
    32       * <p>
    33       * <strong>Preconditions</strong>:<ul>
    34       * <li><code>len > 0</code> (otherwise an IllegalArgumentException
    35       *     is thrown.)</li>
    36       * </ul>
    37       *
    38       * @param len the length of the string to be generated
    39       * @return random string of hex characters of length <code>len</code>
    40       */
    41      String nextHexString(int len);
    42
    43      /***
    44       * Generates a uniformly distributed random integer between
    45       * <code>lower</code> and <code>upper</code> (endpoints included).
    46       * <p>
    47       * The generated integer will be random, but not cryptographically secure.
    48       * To generate cryptographically secure integer sequences, use
    49       * <code>nextSecureInt</code>.
    50       * <p>
    51       * <strong>Preconditions</strong>:<ul>
    52       * <li><code>lower < upper</code> (otherwise an IllegalArgumentException
    53       *     is thrown.)</li>
    54       * </ul>
    55       *
    56       * @param lower lower bound for generated integer
    57       * @param upper upper bound for generated integer
    58       * @return a random integer greater than or equal to <code>lower</code>
    59       * and less than or equal to <code>upper</code>.
    60       */
    61      int nextInt(int lower, int upper);
    62
    63      /***
    64       * Generates a uniformly distributed random long integer between
    65       * <code>lower</code> and <code>upper</code> (endpoints included).
    66       * <p>
    67       * The generated long integer values will be random, but not
    68       * cryptographically secure.
    69       * To generate cryptographically secure sequences of longs, use
    70       * <code>nextSecureLong</code>
    71       * <p>
    72       * <strong>Preconditions</strong>:<ul>
    73       * <li><code>lower < upper</code> (otherwise an IllegalArgumentException
    74       *     is thrown.)</li>
    75       * </ul>
    76       *
    77       * @param lower lower bound for generated integer
    78       * @param upper upper bound for generated integer
    79       * @return a random integer greater than or equal to <code>lower</code>
    80       * and less than or equal to <code>upper</code>.
    81       */
    82      long nextLong(long lower, long upper);
    83
    84      /***
    85       * Generates a random string of hex characters from a secure random
    86       * sequence.
    87       * <p>
    88       * If cryptographic security is not required,
    89       * use <code>nextHexString()</code>.
    90       * <p>
    91       * <strong>Preconditions</strong>:<ul>
    92       * <li><code>len > 0</code> (otherwise an IllegalArgumentException
    93       *     is thrown.)</li>
    94       * </ul>
    95       * @param len length of return string
    96       * @return the random hex string
    97       */
    98      String nextSecureHexString(int len);
    99
    100     /***
    101      * Generates a uniformly distributed random integer between
    102      * <code>lower</code> and <code>upper</code> (endpoints included)
    103      * from a secure random sequence.
    104      * <p>
    105      * Sequences of integers generated using this method will be
    106      * cryptographically secure. If cryptographic security is not required,
    107      * <code>nextInt</code> should be used instead of this method.
    108      * <p>
    109      * <strong>Definition</strong>:
    110      * <a href="http://en.wikipedia.org/wiki/Cryptographically_secure_pseudo-random_number_generator">
    111      * Secure Random Sequence</a>
    112      * <p>
    113      * <strong>Preconditions</strong>:<ul>
    114      * <li><code>lower < upper</code> (otherwise an IllegalArgumentException
    115      *     is thrown.)</li>
    116      * </ul>
    117      *
    118      * @param lower lower bound for generated integer
    119      * @param upper upper bound for generated integer
    120      * @return a random integer greater than or equal to <code>lower</code>
    121      * and less than or equal to <code>upper</code>.
    122      */
    123     int nextSecureInt(int lower, int upper);
    124
    125     /***
    126      * Generates a random long integer between <code>lower</code>
    127      * and <code>upper</code> (endpoints included).<p>
    128      * Sequences of long values generated using this method will be
    129      * cryptographically secure. If cryptographic security is not required,
    130      * <code>nextLong</code> should be used instead of this method.
    131      * <p>
    132      * <strong>Definition</strong>:
    133      * <a href="http://en.wikipedia.org/wiki/Cryptographically_secure_pseudo-random_number_generator">
    134      * Secure Random Sequence</a>
    135      * <p>
    136      * <strong>Preconditions</strong>:<ul>
    137      * <li><code>lower < upper</code> (otherwise an IllegalArgumentException
    138      *     is thrown.)</li>
    139      * </ul>
    140      *
    141      * @param lower lower bound for generated integer
    142      * @param upper upper bound for generated integer
    143      * @return a long integer greater than or equal to <code>lower</code>
    144      * and less than or equal to <code>upper</code>.
    145      */
    146     long nextSecureLong(long lower, long upper);
    147
    148     /***
    149      * Generates a random value from the Poisson distribution with
    150      * the given mean.
    151      * <p>
    152      * <strong>Definition</strong>:
    153      * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda366j.htm">
    154      * Poisson Distribution</a>
    155      * <p>
    156      * <strong>Preconditions</strong>: <ul>
    157      * <li>The specified mean <i>must</i> be positive (otherwise an
    158      *     IllegalArgumentException is thrown.)</li>
    159      * </ul>
    160      * @param mean Mean of the distribution
    161      * @return poisson deviate with the specified mean
    162      */
    163     long nextPoisson(double mean);
    164
    165     /***
    166      * Generates a random value from the
    167      * Normal (or Gaussian) distribution with the given mean
    168      * and standard deviation.
    169      * <p>
    170      * <strong>Definition</strong>:
    171      * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3661.htm">
    172      * Normal Distribution</a>
    173      * <p>
    174      * <strong>Preconditions</strong>: <ul>
    175      * <li><code>sigma > 0</code> (otherwise an IllegalArgumentException
    176      *     is thrown.)</li>
    177      * </ul>
    178      * @param mu Mean of the distribution
    179      * @param sigma Standard deviation of the distribution
    180      * @return random value from Gaussian distribution with mean = mu,
    181      * standard deviation = sigma
    182      */
    183     double nextGaussian(double mu, double sigma);
    184
    185     /***
    186      * Generates a random value from the exponential distribution
    187      * with expected value = <code>mean</code>.
    188      * <p>
    189      * <strong>Definition</strong>:
    190      * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3667.htm">
    191      * Exponential Distribution</a>
    192      * <p>
    193      * <strong>Preconditions</strong>: <ul>
    194      * <li><code>mu >= 0</code> (otherwise an IllegalArgumentException
    195      *     is thrown.)</li>
    196      * </ul>
    197      * @param mean Mean of the distribution
    198      * @return random value from exponential distribution
    199      */
    200     double nextExponential(double mean);
    201
    202     /***
    203      * Generates a uniformly distributed random value from the open interval
    204      * (<code>lower</code>,<code>upper</code>) (i.e., endpoints 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</code> and
    209      * <code>upper - lower</code> are the
    210      * <a href = "http://www.itl.nist.gov/div898/handbook/eda/section3/eda364.htm">
    211      * location and scale parameters</a>, respectively.
    212      * <p>
    213      * <strong>Preconditions</strong>:<ul>
    214      * <li><code>lower < upper</code> (otherwise an IllegalArgumentException
    215      *     is thrown.)</li>
    216      * </ul>
    217      *
    218      * @param lower lower endpoint of the interval of support
    219      * @param upper upper endpoint of the interval of support
    220      * @return uniformly distributed random value between lower
    221      * and upper (exclusive)
    222      */
    223     double nextUniform(double lower, double upper);
    224
    225     /***
    226      * Generates an integer array of length <code>k</code> whose entries
    227      * are selected randomly, without repetition, from the integers <code>
    228      * 0 through n-1</code> (inclusive).
    229      * <p>
    230      * Generated arrays represent permutations
    231      * of <code>n</code> taken <code>k</code> at a time.
    232      * <p>
    233      * <strong>Preconditions:</strong><ul>
    234      * <li> <code>k <= n</code></li>
    235      * <li> <code>n > 0</code> </li>
    236      * </ul>
    237      * If the preconditions are not met, an IllegalArgumentException is
    238      * thrown.
    239      *
    240      * @param n domain of the permutation
    241      * @param k size of the permutation
    242      * @return random k-permutation of n
    243      */
    244     int[] nextPermutation(int n, int k);
    245
    246     /***
    247      * Returns an array of <code>k</code> objects selected randomly
    248      * from the Collection <code>c</code>.
    249      * <p>
    250      * Sampling from <code>c</code>
    251      * is without replacement; but if <code>c</code> contains identical
    252      * objects, the sample may include repeats.  If all elements of <code>
    253      * c</code> are distinct, the resulting object array represents a
    254      * <a href="http://rkb.home.cern.ch/rkb/AN16pp/node250.html#SECTION0002500000000000000000">
    255      * Simple Random Sample</a> of size
    256      * <code>k</code> from the elements of <code>c</code>.
    257      * <p>
    258      * <strong>Preconditions:</strong><ul>
    259      * <li> k must be less than or equal to the size of c </li>
    260      * <li> c must not be empty </li>
    261      * </ul>
    262      * If the preconditions are not met, an IllegalArgumentException is
    263      * thrown.
    264      *
    265      * @param c collection to be sampled
    266      * @param k size of the sample
    267      * @return random sample of k elements from c
    268      */
    269     Object[] nextSample(Collection c, int k);
    270 }