Commons Math example source code file (RandomData.java)

This example Commons Math source code file (RandomData.java) is included in the DevDaily.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Java - Commons Math tags/keywords

object, object, randomdata, randomdata, string, string, util

The Commons Math RandomData.java source code

/*
 * 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 05:05:37 -0400 (Tue, 02 Jun 2009) $
 */
public interface RandomData {
    /**
     * Generates a random string of hex characters of length
     * <code>len.
     * <p>
     * The generated string will be random, but not cryptographically
     * secure. To generate cryptographically secure strings, use
     * <code>nextSecureHexString

     * <p>
     * <strong>Preconditions:

     * <li>len > 0 (otherwise an IllegalArgumentException
     *     is thrown.)</li>
     * </ul>

     *
     * @param len the length of the string to be generated
     * @return random string of hex characters of length <code>len
     */
    String nextHexString(int len);

    /**
     * Generates a uniformly distributed random integer between
     * <code>lower and upper (endpoints included).
     * <p>
     * The generated integer will be random, but not cryptographically secure.
     * To generate cryptographically secure integer sequences, use
     * <code>nextSecureInt.

     * <p>
     * <strong>Preconditions:

     * <li>lower < upper (otherwise an IllegalArgumentException
     *     is thrown.)</li>
     * </ul>

     *
     * @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
     * and less than or equal to <code>upper.
     */
    int nextInt(int lower, int upper);

    /**
     * Generates a uniformly distributed random long integer between
     * <code>lower and upper (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

     * <p>
     * <strong>Preconditions:

     * <li>lower < upper (otherwise an IllegalArgumentException
     *     is thrown.)</li>
     * </ul>

     *
     * @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
     * and less than or equal to <code>upper.
     */
    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().

     * <p>
     * <strong>Preconditions:

     * <li>len > 0 (otherwise an IllegalArgumentException
     *     is thrown.)</li>
     * </ul>

     * @param len length of return string
     * @return the random hex string
     */
    String nextSecureHexString(int len);

    /**
     * Generates a uniformly distributed random integer between
     * <code>lower and upper (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 should be used instead of this method.

     * <p>
     * <strong>Definition:
     * <a href="http://en.wikipedia.org/wiki/Cryptographically_secure_pseudo-random_number_generator">
     * Secure Random Sequence</a>

     * <p>
     * <strong>Preconditions:

     * <li>lower < upper (otherwise an IllegalArgumentException
     *     is thrown.)</li>
     * </ul>

     *
     * @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
     * and less than or equal to <code>upper.
     */
    int nextSecureInt(int lower, int upper);

    /**
     * Generates a random long integer between <code>lower
     * and <code>upper (endpoints included).
     * <p>
     * Sequences of long values generated using this method will be
     * cryptographically secure. If cryptographic security is not required,
     * <code>nextLong should be used instead of this method.

     * <p>
     * <strong>Definition:
     * <a href="http://en.wikipedia.org/wiki/Cryptographically_secure_pseudo-random_number_generator">
     * Secure Random Sequence</a>

     * <p>
     * <strong>Preconditions:

     * <li>lower < upper (otherwise an IllegalArgumentException
     *     is thrown.)</li>
     * </ul>

     *
     * @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
     * and less than or equal to <code>upper.
     */
    long nextSecureLong(long lower, long upper);

    /**
     * Generates a random value from the Poisson distribution with
     * the given mean.
     * <p>
     * <strong>Definition:
     * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda366j.htm">
     * Poisson Distribution</a>

     * <p>
     * <strong>Preconditions: 

     * <li>The specified mean must be positive (otherwise an
     *     IllegalArgumentException is thrown.)</li>
     * </ul>

     * @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:
     * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3661.htm">
     * Normal Distribution</a>

     * <p>
     * <strong>Preconditions: 

     * <li>sigma > 0 (otherwise an IllegalArgumentException
     *     is thrown.)</li>
     * </ul>

     * @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.
     * <p>
     * <strong>Definition:
     * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3667.htm">
     * Exponential Distribution</a>

     * <p>
     * <strong>Preconditions: 

     * <li>mu >= 0 (otherwise an IllegalArgumentException
     *     is thrown.)</li>
     * </ul>

     * @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,upper) (i.e., endpoints excluded).
     * <p>
     * <strong>Definition:
     * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3662.htm">
     * Uniform Distribution</a> lower and
     * <code>upper - lower are the
     * <a href = "http://www.itl.nist.gov/div898/handbook/eda/section3/eda364.htm">
     * location and scale parameters</a>, respectively.

     * <p>
     * <strong>Preconditions:

     * <li>lower < upper (otherwise an IllegalArgumentException
     *     is thrown.)</li>
     * </ul>

     *
     * @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 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 taken k at a time.

     * <p>
     * <strong>Preconditions:

     * <li> k <= n
     * <li> n > 0 
     * </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 objects selected randomly
     * from the Collection <code>c.
     * <p>
     * Sampling from <code>c
     * is without replacement; but if <code>c 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 from the elements of c.

     * <p>
     * <strong>Preconditions:

     * <li> k must be less than or equal to the size of c 
     * <li> c must not be empty 
     * </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);
}