View Javadoc

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 05:05:37 -0400 (Tue, 02 Jun 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 }