001: /*
002: * Copyright 2003-2004 The Apache Software Foundation.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016:
017: package org.apache.commons.math.random;
018:
019: import java.util.Collection;
020:
021: /**
022: * Random data generation utilities.
023: * @version $Revision: 355770 $ $Date: 2005-12-10 12:48:57 -0700 (Sat, 10 Dec 2005) $
024: */
025: public interface RandomData {
026: /**
027: * Generates a random string of hex characters of length
028: * <code>len</code>.
029: * <p>
030: * The generated string will be random, but not cryptographically
031: * secure. To generate cryptographically secure strings, use
032: * <code>nextSecureHexString</code>
033: * <p>
034: * <strong>Preconditions</strong>:<ul>
035: * <li><code>len > 0</code> (otherwise an IllegalArgumentException
036: * is thrown.)</li>
037: * </ul>
038: *
039: * @param len the length of the string to be generated
040: * @return random string of hex characters of length <code>len</code>
041: */
042: String nextHexString(int len);
043:
044: /**
045: * Generates a uniformly distributed random integer between
046: * <code>lower</code> and <code>upper</code> (endpoints included).
047: * <p>
048: * The generated integer will be random, but not cryptographically secure.
049: * To generate cryptographically secure integer sequences, use
050: * <code>nextSecureInt</code>.
051: * <p>
052: * <strong>Preconditions</strong>:<ul>
053: * <li><code>lower < upper</code> (otherwise an IllegalArgumentException
054: * is thrown.)</li>
055: * </ul>
056: *
057: * @param lower lower bound for generated integer
058: * @param upper upper bound for generated integer
059: * @return a random integer greater than or equal to <code>lower</code>
060: * and less than or equal to <code>upper</code>.
061: */
062: int nextInt(int lower, int upper);
063:
064: /**
065: * Generates a uniformly distributed random long integer between
066: * <code>lower</code> and <code>upper</code> (endpoints included).
067: * <p>
068: * The generated long integer values will be random, but not
069: * cryptographically secure.
070: * To generate cryptographically secure sequences of longs, use
071: * <code>nextSecureLong</code>
072: * <p>
073: * <strong>Preconditions</strong>:<ul>
074: * <li><code>lower < upper</code> (otherwise an IllegalArgumentException
075: * is thrown.)</li>
076: * </ul>
077: *
078: * @param lower lower bound for generated integer
079: * @param upper upper bound for generated integer
080: * @return a random integer greater than or equal to <code>lower</code>
081: * and less than or equal to <code>upper</code>.
082: */
083: long nextLong(long lower, long upper);
084:
085: /**
086: * Generates a random string of hex characters from a secure random
087: * sequence.
088: * <p>
089: * If cryptographic security is not required,
090: * use <code>nextHexString()</code>.
091: * <p>
092: * <strong>Preconditions</strong>:<ul>
093: * <li><code>len > 0</code> (otherwise an IllegalArgumentException
094: * is thrown.)</li>
095: * </ul>
096: * @param len length of return string
097: * @return the random hex string
098: */
099: 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.
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>
113: * <p>
114: * <strong>Preconditions</strong>:<ul>
115: * <li><code>lower < upper</code> (otherwise an IllegalArgumentException
116: * is thrown.)</li>
117: * </ul>
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).<p>
129: * Sequences of long values generated using this method will be
130: * cryptographically secure. If cryptographic security is not required,
131: * <code>nextLong</code> should be used instead of this method.
132: * <p>
133: * <strong>Definition</strong>:
134: * <a href="http://en.wikipedia.org/wiki/Cryptographically_secure_pseudo-random_number_generator">
135: * Secure Random Sequence</a>
136: * <p>
137: * <strong>Preconditions</strong>:<ul>
138: * <li><code>lower < upper</code> (otherwise an IllegalArgumentException
139: * is thrown.)</li>
140: * </ul>
141: *
142: * @param lower lower bound for generated integer
143: * @param upper upper bound for generated integer
144: * @return a long integer greater than or equal to <code>lower</code>
145: * and less than or equal to <code>upper</code>.
146: */
147: long nextSecureLong(long lower, long upper);
148:
149: /**
150: * Generates a random value from the Poisson distribution with
151: * the given mean.
152: * <p>
153: * <strong>Definition</strong>:
154: * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda366j.htm">
155: * Poisson Distribution</a>
156: * <p>
157: * <strong>Preconditions</strong>: <ul>
158: * <li>The specified mean <i>must</i> be positive (otherwise an
159: * IllegalArgumentException is thrown.)</li>
160: * </ul>
161: * @param mean Mean of the distribution
162: * @return poisson deviate with the specified mean
163: */
164: long nextPoisson(double mean);
165:
166: /**
167: * Generates a random value from the
168: * Normal (or Gaussian) distribution with the given mean
169: * and standard deviation.
170: * <p>
171: * <strong>Definition</strong>:
172: * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3661.htm">
173: * Normal Distribution</a>
174: * <p>
175: * <strong>Preconditions</strong>: <ul>
176: * <li><code>sigma > 0</code> (otherwise an IllegalArgumentException
177: * is thrown.)</li>
178: * </ul>
179: * @param mu Mean of the distribution
180: * @param sigma Standard deviation of the distribution
181: * @return random value from Gaussian distribution with mean = mu,
182: * standard deviation = sigma
183: */
184: double nextGaussian(double mu, double sigma);
185:
186: /**
187: * Generates a random value from the exponential distribution
188: * with expected value = <code>mean</code>.
189: * <p>
190: * <strong>Definition</strong>:
191: * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3667.htm">
192: * Exponential Distribution</a>
193: * <p>
194: * <strong>Preconditions</strong>: <ul>
195: * <li><code>mu >= 0</code> (otherwise an IllegalArgumentException
196: * is thrown.)</li>
197: * </ul>
198: * @param mean Mean of the distribution
199: * @return random value from exponential distribution
200: */
201: double nextExponential(double mean);
202:
203: /**
204: * Generates a uniformly distributed random value from the open interval
205: * (<code>lower</code>,<code>upper</code>) (i.e., endpoints excluded).
206: * <p>
207: * <strong>Definition</strong>:
208: * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3662.htm">
209: * Uniform Distribution</a> <code>lower</code> and
210: * <code>upper - lower</code> are the
211: * <a href = "http://www.itl.nist.gov/div898/handbook/eda/section3/eda364.htm">
212: * location and scale parameters</a>, respectively.
213: * <p>
214: * <strong>Preconditions</strong>:<ul>
215: * <li><code>lower < upper</code> (otherwise an IllegalArgumentException
216: * is thrown.)</li>
217: * </ul>
218: *
219: * @param lower lower endpoint of the interval of support
220: * @param upper upper endpoint of the interval of support
221: * @return uniformly distributed random value between lower
222: * and upper (exclusive)
223: */
224: double nextUniform(double lower, double upper);
225:
226: /**
227: * Generates an integer array of length <code>k</code> whose entries
228: * are selected randomly, without repetition, from the integers <code>
229: * 0 through n-1</code> (inclusive).
230: * <p>
231: * Generated arrays represent permutations
232: * of <code>n</code> taken <code>k</code> at a time.
233: * <p>
234: * <strong>Preconditions:</strong><ul>
235: * <li> <code>k <= n</code></li>
236: * <li> <code>n > 0</code> </li>
237: * </ul>
238: * If the preconditions are not met, an IllegalArgumentException is
239: * thrown.
240: *
241: * @param n domain of the permutation
242: * @param k size of the permutation
243: * @return random k-permutation of n
244: */
245: int[] nextPermutation(int n, int k);
246:
247: /**
248: * Returns an array of <code>k</code> objects selected randomly
249: * from the Collection <code>c</code>.
250: * <p>
251: * Sampling from <code>c</code>
252: * is without replacement; but if <code>c</code> contains identical
253: * objects, the sample may include repeats. If all elements of <code>
254: * c</code> are distinct, the resulting object array represents a
255: * <a href="http://rkb.home.cern.ch/rkb/AN16pp/node250.html#SECTION0002500000000000000000">
256: * Simple Random Sample</a> of size
257: * <code>k</code> from the elements of <code>c</code>.
258: * <p>
259: * <strong>Preconditions:</strong><ul>
260: * <li> k must be less than or equal to the size of c </li>
261: * <li> c must not be empty </li>
262: * </ul>
263: * If the preconditions are not met, an IllegalArgumentException is
264: * thrown.
265: *
266: * @param c collection to be sampled
267: * @param k size of the sample
268: * @return random sample of k elements from c
269: */
270: Object[] nextSample(Collection c, int k);
271: }
|