Java example source code file (RandomData.java)

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

Learn more about this Java project at its project page.

Java - Java tags/keywords

deprecated, notanumberexception, notfinitenumberexception, notstrictlypositiveexception, numberistoolargeexception, object, randomdata, string, util

The RandomData.java Java example 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.math3.random;
import java.util.Collection;

import org.apache.commons.math3.exception.NotANumberException;
import org.apache.commons.math3.exception.NotFiniteNumberException;
import org.apache.commons.math3.exception.NotStrictlyPositiveException;
import org.apache.commons.math3.exception.NumberIsTooLargeException;

/**
 * Random data generation utilities.
 * @deprecated to be removed in 4.0.  Use {@link RandomDataGenerator} directly
 */
@Deprecated
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
     * {@link #nextSecureHexString(int)}.
     * </p>
     *
     * @param len the length of the string to be generated
     * @return a random string of hex characters of length {@code len}
     * @throws NotStrictlyPositiveException
     * if {@code len <= 0}
     */
    String nextHexString(int len) throws NotStrictlyPositiveException;

    /**
     * Generates a uniformly distributed random integer between {@code lower}
     * and {@code upper} (endpoints included).
     * <p>
     * The generated integer will be random, but not cryptographically secure.
     * To generate cryptographically secure integer sequences, use
     * {@link #nextSecureInt(int, int)}.
     * </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}
     * and less than or equal to {@code upper}
     * @throws NumberIsTooLargeException if {@code lower >= upper}
     */
    int nextInt(int lower, int upper) throws NumberIsTooLargeException;

    /**
     * Generates a uniformly distributed random long integer between
     * {@code lower} and {@code upper} (endpoints included).
     * <p>
     * The generated long integer values will be random, but not
     * cryptographically secure. To generate cryptographically secure sequences
     * of longs, use {@link #nextSecureLong(long, long)}.
     * </p>
     *
     * @param lower lower bound for generated long integer
     * @param upper upper bound for generated long integer
     * @return a random long integer greater than or equal to {@code lower} and
     * less than or equal to {@code upper}
     * @throws NumberIsTooLargeException if {@code lower >= upper}
     */
    long nextLong(long lower, long upper) throws NumberIsTooLargeException;

    /**
     * Generates a random string of hex characters from a secure random
     * sequence.
     * <p>
     * If cryptographic security is not required, use
     * {@link #nextHexString(int)}.
     * </p>
     *
     * @param len the length of the string to be generated
     * @return a random string of hex characters of length {@code len}
     * @throws NotStrictlyPositiveException if {@code len <= 0}
     */
    String nextSecureHexString(int len) throws NotStrictlyPositiveException;

    /**
     * Generates a uniformly distributed random integer between {@code lower}
     * and {@code 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,
     * {@link #nextInt(int, int)} should be used instead of this method.</p>
     * <p>
     * <strong>Definition:
     * <a href="http://en.wikipedia.org/wiki/Cryptographically_secure_pseudo-random_number_generator">
     * Secure Random Sequence</a>

     *
     * @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}.
     * @throws NumberIsTooLargeException if {@code lower >= upper}.
     */
    int nextSecureInt(int lower, int upper) throws NumberIsTooLargeException;

    /**
     * Generates a uniformly distributed random long integer between
     * {@code lower} and {@code upper} (endpoints included) from a secure random
     * sequence.
     * <p>
     * Sequences of long values generated using this method will be
     * cryptographically secure. If cryptographic security is not required,
     * {@link #nextLong(long, long)} should be used instead of this method.</p>
     * <p>
     * <strong>Definition:
     * <a href="http://en.wikipedia.org/wiki/Cryptographically_secure_pseudo-random_number_generator">
     * Secure Random Sequence</a>

     *
     * @param lower lower bound for generated integer
     * @param upper upper bound for generated integer
     * @return a random long integer greater than or equal to {@code lower} and
     * less than or equal to {@code upper}.
     * @throws NumberIsTooLargeException if {@code lower >= upper}.
     */
    long nextSecureLong(long lower, long upper) throws NumberIsTooLargeException;

    /**
     * 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>

     *
     * @param mean the mean of the Poisson distribution
     * @return a random value following the specified Poisson distribution
     * @throws NotStrictlyPositiveException if {@code mean <= 0}.
     */
    long nextPoisson(double mean) throws NotStrictlyPositiveException;

    /**
     * Generates a random value from the Normal (or Gaussian) distribution with
     * specified mean and standard deviation.
     * <p>
     * <strong>Definition:
     * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3661.htm">
     * Normal Distribution</a>

     *
     * @param mu the mean of the distribution
     * @param sigma the standard deviation of the distribution
     * @return a random value following the specified Gaussian distribution
     * @throws NotStrictlyPositiveException if {@code sigma <= 0}.
     */
    double nextGaussian(double mu, double sigma) throws NotStrictlyPositiveException;

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

     *
     * @param mean the mean of the distribution
     * @return a random value following the specified exponential distribution
     * @throws NotStrictlyPositiveException if {@code mean <= 0}.
     */
    double nextExponential(double mean) throws NotStrictlyPositiveException;

    /**
     * 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> {@code 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.

     *
     * @param lower the exclusive lower bound of the support
     * @param upper the exclusive upper bound of the support
     * @return a uniformly distributed random value between lower and upper
     * (exclusive)
     * @throws NumberIsTooLargeException if {@code lower >= upper}
     * @throws NotFiniteNumberException if one of the bounds is infinite
     * @throws NotANumberException if one of the bounds is NaN
     */
    double nextUniform(double lower, double upper)
        throws NumberIsTooLargeException, NotFiniteNumberException, NotANumberException;

    /**
     * Generates a uniformly distributed random value from the interval
     * {@code (lower, upper)} or the interval {@code [lower, upper)}. The lower
     * bound is thus optionally included, while the upper bound is always
     * excluded.
     * <p>
     * <strong>Definition:
     * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3662.htm">
     * Uniform Distribution</a> {@code 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.

     *
     * @param lower the lower bound of the support
     * @param upper the exclusive upper bound of the support
     * @param lowerInclusive {@code true} if the lower bound is inclusive
     * @return uniformly distributed random value in the {@code (lower, upper)}
     * interval, if {@code lowerInclusive} is {@code false}, or in the
     * {@code [lower, upper)} interval, if {@code lowerInclusive} is
     * {@code true}
     * @throws NumberIsTooLargeException if {@code lower >= upper}
     * @throws NotFiniteNumberException if one of the bounds is infinite
     * @throws NotANumberException if one of the bounds is NaN
     */
    double nextUniform(double lower, double upper, boolean lowerInclusive)
        throws NumberIsTooLargeException, NotFiniteNumberException, NotANumberException;

    /**
     * Generates an integer array of length {@code k} whose entries are selected
     * randomly, without repetition, from the integers {@code 0, ..., n - 1}
     * (inclusive).
     * <p>
     * Generated arrays represent permutations of {@code n} taken {@code k} at a
     * time.</p>
     *
     * @param n the domain of the permutation
     * @param k the size of the permutation
     * @return a random {@code k}-permutation of {@code n}, as an array of
     * integers
     * @throws NumberIsTooLargeException if {@code k > n}.
     * @throws NotStrictlyPositiveException if {@code k <= 0}.
     */
    int[] nextPermutation(int n, int k)
        throws NumberIsTooLargeException, NotStrictlyPositiveException;

    /**
     * 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} 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
     * {@code c}.</p>
     *
     * @param c the collection to be sampled
     * @param k the size of the sample
     * @return a random sample of {@code k} elements from {@code c}
     * @throws NumberIsTooLargeException if {@code k > c.size()}.
     * @throws NotStrictlyPositiveException if {@code k <= 0}.
     */
    Object[] nextSample(Collection<?> c, int k)
        throws NumberIsTooLargeException, NotStrictlyPositiveException;

}