| /* |
| * Licensed to the Apache Software Foundation (ASF) under one or more |
| * contributor license agreements. See the NOTICE file distributed with |
| * this work for additional information regarding copyright ownership. |
| * The ASF licenses this file to You under the Apache License, Version 2.0 |
| * (the "License"); you may not use this file except in compliance with |
| * the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| package org.apache.commons.math.random; |
| import java.util.Collection; |
| |
| /** |
| * Random data generation utilities. |
| * @version $Revision: 780975 $ $Date: 2009-06-02 11:05:37 +0200 (mar. 02 juin 2009) $ |
| */ |
| public interface RandomData { |
| /** |
| * Generates a random string of hex characters of length |
| * <code>len</code>. |
| * <p> |
| * The generated string will be random, but not cryptographically |
| * secure. To generate cryptographically secure strings, use |
| * <code>nextSecureHexString</code></p> |
| * <p> |
| * <strong>Preconditions</strong>:<ul> |
| * <li><code>len > 0</code> (otherwise an IllegalArgumentException |
| * is thrown.)</li> |
| * </ul></p> |
| * |
| * @param len the length of the string to be generated |
| * @return random string of hex characters of length <code>len</code> |
| */ |
| String nextHexString(int len); |
| |
| /** |
| * Generates a uniformly distributed random integer between |
| * <code>lower</code> and <code>upper</code> (endpoints included). |
| * <p> |
| * The generated integer will be random, but not cryptographically secure. |
| * To generate cryptographically secure integer sequences, use |
| * <code>nextSecureInt</code>.</p> |
| * <p> |
| * <strong>Preconditions</strong>:<ul> |
| * <li><code>lower < upper</code> (otherwise an IllegalArgumentException |
| * is thrown.)</li> |
| * </ul></p> |
| * |
| * @param lower lower bound for generated integer |
| * @param upper upper bound for generated integer |
| * @return a random integer greater than or equal to <code>lower</code> |
| * and less than or equal to <code>upper</code>. |
| */ |
| int nextInt(int lower, int upper); |
| |
| /** |
| * Generates a uniformly distributed random long integer between |
| * <code>lower</code> and <code>upper</code> (endpoints included). |
| * <p> |
| * The generated long integer values will be random, but not |
| * cryptographically secure. |
| * To generate cryptographically secure sequences of longs, use |
| * <code>nextSecureLong</code></p> |
| * <p> |
| * <strong>Preconditions</strong>:<ul> |
| * <li><code>lower < upper</code> (otherwise an IllegalArgumentException |
| * is thrown.)</li> |
| * </ul></p> |
| * |
| * @param lower lower bound for generated integer |
| * @param upper upper bound for generated integer |
| * @return a random integer greater than or equal to <code>lower</code> |
| * and less than or equal to <code>upper</code>. |
| */ |
| long nextLong(long lower, long upper); |
| |
| /** |
| * Generates a random string of hex characters from a secure random |
| * sequence. |
| * <p> |
| * If cryptographic security is not required, |
| * use <code>nextHexString()</code>.</p> |
| * <p> |
| * <strong>Preconditions</strong>:<ul> |
| * <li><code>len > 0</code> (otherwise an IllegalArgumentException |
| * is thrown.)</li> |
| * </ul></p> |
| * @param len length of return string |
| * @return the random hex string |
| */ |
| String nextSecureHexString(int len); |
| |
| /** |
| * Generates a uniformly distributed random integer between |
| * <code>lower</code> and <code>upper</code> (endpoints included) |
| * from a secure random sequence. |
| * <p> |
| * Sequences of integers generated using this method will be |
| * cryptographically secure. If cryptographic security is not required, |
| * <code>nextInt</code> should be used instead of this method.</p> |
| * <p> |
| * <strong>Definition</strong>: |
| * <a href="http://en.wikipedia.org/wiki/Cryptographically_secure_pseudo-random_number_generator"> |
| * Secure Random Sequence</a></p> |
| * <p> |
| * <strong>Preconditions</strong>:<ul> |
| * <li><code>lower < upper</code> (otherwise an IllegalArgumentException |
| * is thrown.)</li> |
| * </ul></p> |
| * |
| * @param lower lower bound for generated integer |
| * @param upper upper bound for generated integer |
| * @return a random integer greater than or equal to <code>lower</code> |
| * and less than or equal to <code>upper</code>. |
| */ |
| int nextSecureInt(int lower, int upper); |
| |
| /** |
| * Generates a random long integer between <code>lower</code> |
| * and <code>upper</code> (endpoints included). |
| * <p> |
| * Sequences of long values generated using this method will be |
| * cryptographically secure. If cryptographic security is not required, |
| * <code>nextLong</code> should be used instead of this method.</p> |
| * <p> |
| * <strong>Definition</strong>: |
| * <a href="http://en.wikipedia.org/wiki/Cryptographically_secure_pseudo-random_number_generator"> |
| * Secure Random Sequence</a></p> |
| * <p> |
| * <strong>Preconditions</strong>:<ul> |
| * <li><code>lower < upper</code> (otherwise an IllegalArgumentException |
| * is thrown.)</li> |
| * </ul></p> |
| * |
| * @param lower lower bound for generated integer |
| * @param upper upper bound for generated integer |
| * @return a long integer greater than or equal to <code>lower</code> |
| * and less than or equal to <code>upper</code>. |
| */ |
| long nextSecureLong(long lower, long upper); |
| |
| /** |
| * Generates a random value from the Poisson distribution with |
| * the given mean. |
| * <p> |
| * <strong>Definition</strong>: |
| * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda366j.htm"> |
| * Poisson Distribution</a></p> |
| * <p> |
| * <strong>Preconditions</strong>: <ul> |
| * <li>The specified mean <i>must</i> be positive (otherwise an |
| * IllegalArgumentException is thrown.)</li> |
| * </ul></p> |
| * @param mean Mean of the distribution |
| * @return poisson deviate with the specified mean |
| */ |
| long nextPoisson(double mean); |
| |
| /** |
| * Generates a random value from the |
| * Normal (or Gaussian) distribution with the given mean |
| * and standard deviation. |
| * <p> |
| * <strong>Definition</strong>: |
| * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3661.htm"> |
| * Normal Distribution</a></p> |
| * <p> |
| * <strong>Preconditions</strong>: <ul> |
| * <li><code>sigma > 0</code> (otherwise an IllegalArgumentException |
| * is thrown.)</li> |
| * </ul></p> |
| * @param mu Mean of the distribution |
| * @param sigma Standard deviation of the distribution |
| * @return random value from Gaussian distribution with mean = mu, |
| * standard deviation = sigma |
| */ |
| double nextGaussian(double mu, double sigma); |
| |
| /** |
| * Generates a random value from the exponential distribution |
| * with expected value = <code>mean</code>. |
| * <p> |
| * <strong>Definition</strong>: |
| * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3667.htm"> |
| * Exponential Distribution</a></p> |
| * <p> |
| * <strong>Preconditions</strong>: <ul> |
| * <li><code>mu >= 0</code> (otherwise an IllegalArgumentException |
| * is thrown.)</li> |
| * </ul></p> |
| * @param mean Mean of the distribution |
| * @return random value from exponential distribution |
| */ |
| double nextExponential(double mean); |
| |
| /** |
| * Generates a uniformly distributed random value from the open interval |
| * (<code>lower</code>,<code>upper</code>) (i.e., endpoints excluded). |
| * <p> |
| * <strong>Definition</strong>: |
| * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3662.htm"> |
| * Uniform Distribution</a> <code>lower</code> and |
| * <code>upper - lower</code> are the |
| * <a href = "http://www.itl.nist.gov/div898/handbook/eda/section3/eda364.htm"> |
| * location and scale parameters</a>, respectively.</p> |
| * <p> |
| * <strong>Preconditions</strong>:<ul> |
| * <li><code>lower < upper</code> (otherwise an IllegalArgumentException |
| * is thrown.)</li> |
| * </ul></p> |
| * |
| * @param lower lower endpoint of the interval of support |
| * @param upper upper endpoint of the interval of support |
| * @return uniformly distributed random value between lower |
| * and upper (exclusive) |
| */ |
| double nextUniform(double lower, double upper); |
| |
| /** |
| * Generates an integer array of length <code>k</code> whose entries |
| * are selected randomly, without repetition, from the integers <code> |
| * 0 through n-1</code> (inclusive). |
| * <p> |
| * Generated arrays represent permutations |
| * of <code>n</code> taken <code>k</code> at a time.</p> |
| * <p> |
| * <strong>Preconditions:</strong><ul> |
| * <li> <code>k <= n</code></li> |
| * <li> <code>n > 0</code> </li> |
| * </ul> |
| * If the preconditions are not met, an IllegalArgumentException is |
| * thrown.</p> |
| * |
| * @param n domain of the permutation |
| * @param k size of the permutation |
| * @return random k-permutation of n |
| */ |
| int[] nextPermutation(int n, int k); |
| |
| /** |
| * Returns an array of <code>k</code> objects selected randomly |
| * from the Collection <code>c</code>. |
| * <p> |
| * Sampling from <code>c</code> |
| * is without replacement; but if <code>c</code> contains identical |
| * objects, the sample may include repeats. If all elements of <code> |
| * c</code> are distinct, the resulting object array represents a |
| * <a href="http://rkb.home.cern.ch/rkb/AN16pp/node250.html#SECTION0002500000000000000000"> |
| * Simple Random Sample</a> of size |
| * <code>k</code> from the elements of <code>c</code>.</p> |
| * <p> |
| * <strong>Preconditions:</strong><ul> |
| * <li> k must be less than or equal to the size of c </li> |
| * <li> c must not be empty </li> |
| * </ul> |
| * If the preconditions are not met, an IllegalArgumentException is |
| * thrown.</p> |
| * |
| * @param c collection to be sampled |
| * @param k size of the sample |
| * @return random sample of k elements from c |
| */ |
| Object[] nextSample(Collection<?> c, int k); |
| } |
