KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > commons > math > random > 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 JavaDoc;
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 JavaDoc 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 JavaDoc 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 JavaDoc[] nextSample(Collection JavaDoc c, int k);
270 }
271
Popular Tags