RandomData


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$ $Date: 2005-02-26 05:11:52 -0800 (Sat, 26 Feb 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 }
271
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags