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