1
2
3
4
5
6
7
8
9
10
11
12
13
14
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 }