Package org.apache.commons.lang3

Class RandomUtils

  • public class RandomUtils
extends java.lang.Object
    Supplements the standard Random class.

    Use secure() to get the singleton instance based on SecureRandom() which uses a secure random number generator implementing the default random number algorithm.

    Use secureStrong() to get the singleton instance based on SecureRandom.getInstanceStrong() which uses an instance that was selected by using the algorithms/providers specified in the securerandom.strongAlgorithms Security property.

    Use insecure() to get the singleton instance based on ThreadLocalRandom.current() which is not cryptographically secure. In addition, instances do not use a cryptographically random seed unless the system property java.util.secureRandomSeed is set to true.

    Starting in version 3.17.0, the method secure() uses SecureRandom() instead of SecureRandom.getInstanceStrong(), and adds secureStrong().

    Starting in version 3.16.0, this class uses secure() for static methods and adds insecure().

    Starting in version 3.15.0, this class uses SecureRandom.getInstanceStrong() for static methods.

    Before version 3.15.0, this class used ThreadLocalRandom.current() for static methods, which is not cryptographically secure.

    Please note that the Apache Commons project provides a component dedicated to pseudo-random number generation, namely Commons RNG, that may be a better choice for applications with more stringent requirements (performance and/or correctness).

    Since:
    3.3
    See Also:
    secure(), secureStrong(), insecure(), SecureRandom(), SecureRandom.getInstanceStrong(), ThreadLocalRandom.current(), RandomStringUtils

    • Field Detail

      • SECURE_STRONG_SUPPLIER

        private static final java.util.function.Supplier<java.util.Random> SECURE_STRONG_SUPPLIER

      • SECURE_STRONG

        private static RandomUtils SECURE_STRONG

      • SECURE_RANDOM_STRONG

        private static final java.lang.ThreadLocal<java.security.SecureRandom> SECURE_RANDOM_STRONG

      • random

        private final java.util.function.Supplier<java.util.Random> random

    • Constructor Detail

      • RandomUtils

        @Deprecated
public RandomUtils()
        Deprecated.
        TODO Make private in 4.0.
        RandomUtils instances should NOT be constructed in standard programming. Instead, the class should be used as RandomUtils.nextBytes(5);.

        This constructor is public to permit tools that require a JavaBean instance to operate.

      • RandomUtils

        private RandomUtils​(java.util.function.Supplier<java.util.Random> random)

    • Method Detail

      • insecure

        public static RandomUtils insecure()
        Gets the singleton instance based on ThreadLocalRandom.current(); which is not cryptographically secure; use secure() to use an algorithms/providers specified in the securerandom.strongAlgorithms Security property.

        The method ThreadLocalRandom.current() is called on-demand.

        Returns:
        the singleton instance based on ThreadLocalRandom.current().
        Since:
        3.17.0
        See Also:
        ThreadLocalRandom.current(), secure()

      • nextBoolean

        @Deprecated
public static boolean nextBoolean()
        Deprecated.
        Use secure(), secureStrong(), or insecure().
        Generates a random boolean value.
        Returns:
        the random boolean.
        Since:
        3.5

      • nextBytes

        @Deprecated
public static byte[] nextBytes​(int count)
        Deprecated.
        Use secure(), secureStrong(), or insecure().
        Generates an array of random bytes.
        Parameters:
        count - the size of the returned array.
        Returns:
        the random byte array.
        Throws:
        java.lang.IllegalArgumentException - if count is negative.

      • nextDouble

        @Deprecated
public static double nextDouble​(double startInclusive,
                                double endExclusive)
        Deprecated.
        Use secure(), secureStrong(), or insecure().
        Generates a random double within the specified range.
        Parameters:
        startInclusive - the smallest value that can be returned, must be non-negative.
        endExclusive - the upper bound (not included).
        Returns:
        the random double.
        Throws:
        java.lang.IllegalArgumentException - if startInclusive > endExclusive or if startInclusive is negative.

      • nextFloat

        @Deprecated
public static float nextFloat​(float startInclusive,
                              float endExclusive)
        Deprecated.
        Use secure(), secureStrong(), or insecure().
        Generates a random float within the specified range.
        Parameters:
        startInclusive - the smallest value that can be returned, must be non-negative.
        endExclusive - the upper bound (not included).
        Returns:
        the random float
        Throws:
        java.lang.IllegalArgumentException - if startInclusive > endExclusive or if startInclusive is negative.

      • nextInt

        @Deprecated
public static int nextInt()
        Deprecated.
        Use secure(), secureStrong(), or insecure().
        Generates a random int between 0 (inclusive) and Integer.MAX_VALUE (exclusive).
        Returns:
        the random integer.
        Since:
        3.5
        See Also:
        nextInt(int, int)

      • nextInt

        @Deprecated
public static int nextInt​(int startInclusive,
                          int endExclusive)
        Deprecated.
        Use secure(), secureStrong(), or insecure().
        Generates a random integer within the specified range.
        Parameters:
        startInclusive - the smallest value that can be returned, must be non-negative.
        endExclusive - the upper bound (not included).
        Returns:
        the random integer.
        Throws:
        java.lang.IllegalArgumentException - if startInclusive > endExclusive or if startInclusive is negative.

      • nextLong

        @Deprecated
public static long nextLong​(long startInclusive,
                            long endExclusive)
        Deprecated.
        Use secure(), secureStrong(), or insecure().
        Generates a random long within the specified range.
        Parameters:
        startInclusive - the smallest value that can be returned, must be non-negative.
        endExclusive - the upper bound (not included).
        Returns:
        the random long.
        Throws:
        java.lang.IllegalArgumentException - if startInclusive > endExclusive or if startInclusive is negative.

      • secure

        public static RandomUtils secure()
        Gets the singleton instance based on SecureRandom() which uses an algorithms/providers specified in the securerandom.strongAlgorithms Security property.

        The method SecureRandom() is called on-demand.

        Returns:
        the singleton instance based on SecureRandom().
        Since:
        3.16.0
        See Also:
        SecureRandom()

      • secureRandom

        static java.security.SecureRandom secureRandom()

      • secureStrong

        public static RandomUtils secureStrong()
        Gets the singleton instance based on SecureRandom.getInstanceStrong() which uses an algorithms/providers specified in the securerandom.strongAlgorithms Security property.

        The method SecureRandom.getInstanceStrong() is called on-demand.

        Returns:
        the singleton instance based on SecureRandom.getInstanceStrong().
        Since:
        3.17.0
        See Also:
        SecureRandom.getInstanceStrong()

      • random

        java.util.Random random()

      • randomBoolean

        public boolean randomBoolean()
        Generates a random boolean value.
        Returns:
        the random boolean.
        Since:
        3.16.0

      • randomBytes

        public byte[] randomBytes​(int count)
        Generates an array of random bytes.
        Parameters:
        count - the size of the returned array.
        Returns:
        the random byte array.
        Throws:
        java.lang.IllegalArgumentException - if count is negative
        Since:
        3.16.0

      • randomDouble

        public double randomDouble()
        Generates a random double between 0 (inclusive) and Double.MAX_VALUE (exclusive).
        Returns:
        the random double.
        Since:
        3.16.0
        See Also:
        randomDouble(double, double)

      • randomDouble

        public double randomDouble​(double startInclusive,
                           double endExclusive)
        Generates a random double within the specified range.
        Parameters:
        startInclusive - the smallest value that can be returned, must be non-negative.
        endExclusive - the upper bound (not included).
        Returns:
        the random double
        Throws:
        java.lang.IllegalArgumentException - if startInclusive > endExclusive or if startInclusive is negative.
        Since:
        3.16.0

      • randomFloat

        public float randomFloat()
        Generates a random float between 0 (inclusive) and Float.MAX_VALUE (exclusive).
        Returns:
        the random float.
        Since:
        3.16.0
        See Also:
        randomFloat(float, float)

      • randomFloat

        public float randomFloat​(float startInclusive,
                         float endExclusive)
        Generates a random float within the specified range.
        Parameters:
        startInclusive - the smallest value that can be returned, must be non-negative.
        endExclusive - the upper bound (not included).
        Returns:
        the random float.
        Throws:
        java.lang.IllegalArgumentException - if startInclusive > endExclusive or if startInclusive is negative.

      • randomInt

        public int randomInt()
        Generates a random int between 0 (inclusive) and Integer.MAX_VALUE (exclusive).
        Returns:
        the random integer.
        Since:
        3.16.0
        See Also:
        randomInt(int, int)

      • randomInt

        public int randomInt​(int startInclusive,
                     int endExclusive)
        Generates a random integer within the specified range.
        Parameters:
        startInclusive - the smallest value that can be returned, must be non-negative.
        endExclusive - the upper bound (not included).
        Returns:
        the random integer.
        Throws:
        java.lang.IllegalArgumentException - if startInclusive > endExclusive or if startInclusive is negative.
        Since:
        3.16.0

      • randomLong

        public long randomLong()
        Generates a random long between 0 (inclusive) and Long.MAX_VALUE (exclusive).
        Returns:
        the random long.
        Since:
        3.16.0
        See Also:
        randomLong(long, long)

      • randomLong

        private long randomLong​(long n)
        Generates a long value between 0 (inclusive) and the specified value (exclusive).
        Parameters:
        n - Bound on the random number to be returned. Must be positive.
        Returns:
        a random long value between 0 (inclusive) and n (exclusive).

      • randomLong

        public long randomLong​(long startInclusive,
                       long endExclusive)
        Generates a random long within the specified range.
        Parameters:
        startInclusive - the smallest value that can be returned, must be non-negative.
        endExclusive - the upper bound (not included).
        Returns:
        the random long.
        Throws:
        java.lang.IllegalArgumentException - if startInclusive > endExclusive or if startInclusive is negative.
        Since:
        3.16.0

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object