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 }