Class RandomUtils

java.lang.Object
org.apache.commons.lang3.RandomUtils

public class RandomUtils extends Object
Supplements the standard Random class.

Use secure() to get the singleton instance based on SecureRandom.getInstanceStrong() which uses an 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.

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

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

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:
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private static RandomUtils
     
    private final Supplier<Random>
     
    private static RandomUtils
     
    private static final ThreadLocal<SecureRandom>
     
    private static final Supplier<Random>
     
  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
     
    Deprecated.
    TODO Make private in 4.0.
    private
     
  • Method Summary

    Modifier and Type
    Method
    Description
    (package private) static RandomUtils
    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.
    static boolean
    Generates a random boolean value.
    static byte[]
    nextBytes(int count)
    Generates an array of random bytes.
    static double
    Generates a random double between 0 (inclusive) and Double.MAX_VALUE (exclusive).
    static double
    nextDouble(double startInclusive, double endExclusive)
    Generates a random double within the specified range.
    static float
    Generates a random float between 0 (inclusive) and Float.MAX_VALUE (exclusive).
    static float
    nextFloat(float startInclusive, float endExclusive)
    Generates a random float within the specified range.
    static int
    Generates a random int between 0 (inclusive) and Integer.MAX_VALUE (exclusive).
    static int
    nextInt(int startInclusive, int endExclusive)
    Generates a random integer within the specified range.
    static long
    Generates a random long between 0 (inclusive) and Long.MAX_VALUE (exclusive).
    private static long
    nextLong(long n)
    Generates a long value between 0 (inclusive) and the specified value (exclusive).
    static long
    nextLong(long startInclusive, long endExclusive)
    Generates a random long within the specified range.
    (package private) Random
     
    boolean
    Generates a random boolean value.
    byte[]
    randomBytes(int count)
    Generates an array of random bytes.
    double
    Generates a random double between 0 (inclusive) and Double.MAX_VALUE (exclusive).
    double
    randomDouble(double startInclusive, double endExclusive)
    Generates a random double within the specified range.
    float
    Generates a random float between 0 (inclusive) and Float.MAX_VALUE (exclusive).
    float
    randomFloat(float startInclusive, float endExclusive)
    Generates a random float within the specified range.
    int
    Generates a random int between 0 (inclusive) and Integer.MAX_VALUE (exclusive).
    int
    randomInt(int startInclusive, int endExclusive)
    Generates a random integer within the specified range.
    long
    Generates a random long between 0 (inclusive) and Long.MAX_VALUE (exclusive).
    private long
    randomLong(long n)
    Generates a long value between 0 (inclusive) and the specified value (exclusive).
    long
    randomLong(long startInclusive, long endExclusive)
    Generates a random long within the specified range.
    Gets the singleton instance based on SecureRandom.getInstanceStrong() which uses an algorithms/providers specified in the securerandom.strongAlgorithms Security property.
    (package private) static SecureRandom
     
     

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
  • Field Details

  • Constructor Details

    • 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(Supplier<Random> random)
  • Method Details

    • insecure

      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.16.0
      See Also:
    • nextBoolean

      public static boolean nextBoolean()
      Generates a random boolean value.
      Returns:
      the random boolean
      Since:
      3.5
    • nextBytes

      public static byte[] nextBytes(int count)
      Generates an array of random bytes.
      Parameters:
      count - the size of the returned array
      Returns:
      the random byte array
      Throws:
      IllegalArgumentException - if count is negative
    • nextDouble

      public static double nextDouble()
      Generates a random double between 0 (inclusive) and Double.MAX_VALUE (exclusive).
      Returns:
      the random double
      Since:
      3.5
      See Also:
    • nextDouble

      public static double nextDouble(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:
      IllegalArgumentException - if startInclusive > endExclusive or if startInclusive is negative
    • nextFloat

      public static float nextFloat()
      Generates a random float between 0 (inclusive) and Float.MAX_VALUE (exclusive).
      Returns:
      the random float
      Since:
      3.5
      See Also:
    • nextFloat

      public static float nextFloat(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:
      IllegalArgumentException - if startInclusive > endExclusive or if startInclusive is negative
    • nextInt

      public static int nextInt()
      Generates a random int between 0 (inclusive) and Integer.MAX_VALUE (exclusive).
      Returns:
      the random integer
      Since:
      3.5
      See Also:
    • nextInt

      public static int nextInt(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:
      IllegalArgumentException - if startInclusive > endExclusive or if startInclusive is negative
    • nextLong

      public static long nextLong()
      Generates a random long between 0 (inclusive) and Long.MAX_VALUE (exclusive).
      Returns:
      the random long
      Since:
      3.5
      See Also:
    • nextLong

      private static long nextLong(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).
    • nextLong

      public static long nextLong(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:
      IllegalArgumentException - if startInclusive > endExclusive or if startInclusive is negative
    • secure

      public static RandomUtils secure()
      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.16.0
      See Also:
    • secureRandom

      static SecureRandom secureRandom()
    • random

      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:
      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

      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:
      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

      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:
      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

      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:
      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

      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:
      IllegalArgumentException - if startInclusive > endExclusive or if startInclusive is negative
      Since:
      3.16.0
    • toString

      public String toString()
      Overrides:
      toString in class Object