1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 package org.apache.commons.math.random; 19 import java.util.Collection; 20 21 /** 22 * Random data generation utilities. 23 * @version $Revision: 780975 $ $Date: 2009-06-02 11:05:37 +0200 (mar. 02 juin 2009) $ 24 */ 25 public interface RandomData { 26 /** 27 * Generates a random string of hex characters of length 28 * <code>len</code>. 29 * <p> 30 * The generated string will be random, but not cryptographically 31 * secure. To generate cryptographically secure strings, use 32 * <code>nextSecureHexString</code></p> 33 * <p> 34 * <strong>Preconditions</strong>:<ul> 35 * <li><code>len > 0</code> (otherwise an IllegalArgumentException 36 * is thrown.)</li> 37 * </ul></p> 38 * 39 * @param len the length of the string to be generated 40 * @return random string of hex characters of length <code>len</code> 41 */ 42 String nextHexString(int len); 43 44 /** 45 * Generates a uniformly distributed random integer between 46 * <code>lower</code> and <code>upper</code> (endpoints included). 47 * <p> 48 * The generated integer will be random, but not cryptographically secure. 49 * To generate cryptographically secure integer sequences, use 50 * <code>nextSecureInt</code>.</p> 51 * <p> 52 * <strong>Preconditions</strong>:<ul> 53 * <li><code>lower < upper</code> (otherwise an IllegalArgumentException 54 * is thrown.)</li> 55 * </ul></p> 56 * 57 * @param lower lower bound for generated integer 58 * @param upper upper bound for generated integer 59 * @return a random integer greater than or equal to <code>lower</code> 60 * and less than or equal to <code>upper</code>. 61 */ 62 int nextInt(int lower, int upper); 63 64 /** 65 * Generates a uniformly distributed random long integer between 66 * <code>lower</code> and <code>upper</code> (endpoints included). 67 * <p> 68 * The generated long integer values will be random, but not 69 * cryptographically secure. 70 * To generate cryptographically secure sequences of longs, use 71 * <code>nextSecureLong</code></p> 72 * <p> 73 * <strong>Preconditions</strong>:<ul> 74 * <li><code>lower < upper</code> (otherwise an IllegalArgumentException 75 * is thrown.)</li> 76 * </ul></p> 77 * 78 * @param lower lower bound for generated integer 79 * @param upper upper bound for generated integer 80 * @return a random integer greater than or equal to <code>lower</code> 81 * and less than or equal to <code>upper</code>. 82 */ 83 long nextLong(long lower, long upper); 84 85 /** 86 * Generates a random string of hex characters from a secure random 87 * sequence. 88 * <p> 89 * If cryptographic security is not required, 90 * use <code>nextHexString()</code>.</p> 91 * <p> 92 * <strong>Preconditions</strong>:<ul> 93 * <li><code>len > 0</code> (otherwise an IllegalArgumentException 94 * is thrown.)</li> 95 * </ul></p> 96 * @param len length of return string 97 * @return the random hex string 98 */ 99 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 } 273
