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