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() 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:
  • 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.

  • Method Details

    • insecure

      public static RandomUtils insecure()
      Gets the singleton instance based on ThreadLocalRandom.current(); which is not cryptographically secure; for more secure processing use secure() or secureStrong().

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

      Returns:
      The singleton instance based on ThreadLocalRandom.current().
      Since:
      3.17.0
      See Also:
    • nextBoolean

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

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

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

      @Deprecated public static double nextDouble(double startInclusive, double endExclusive)
      Deprecated.
      Generates a random double within the specified range.

      If the bounds are equal, returns the common bound. If startInclusive is finite and endExclusive is positive infinity, returns Double.MAX_VALUE.

      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 - Thrown if startInclusive > endExclusive or if startInclusive is negative.
    • nextFloat

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

      @Deprecated public static float nextFloat(float startInclusive, float endExclusive)
      Deprecated.
      Generates a random float within the specified range.

      If the bounds are equal, returns the common bound. If startInclusive is finite and endExclusive is positive infinity, returns Float.MAX_VALUE.

      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 - Thrown if startInclusive > endExclusive or if startInclusive is negative.
    • nextInt

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

      @Deprecated public static int nextInt(int startInclusive, int endExclusive)
      Deprecated.
      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 - Thrown if startInclusive > endExclusive or if startInclusive is negative.
    • nextLong

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

      @Deprecated public static long nextLong(long startInclusive, long endExclusive)
      Deprecated.
      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 - Thrown if startInclusive > endExclusive or if startInclusive is negative.
    • secure

      public static RandomUtils secure()
      Gets the singleton instance based on SecureRandom() which uses the default algorithm and provider of SecureRandom.

      The method SecureRandom() is called on-demand.

      Returns:
      The singleton instance based on SecureRandom().
      Since:
      3.16.0
      See Also:
    • 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:
    • 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 - Thrown if count is negative.
      Since:
      3.16.0
    • randomDouble

      public double randomDouble()
      Generates a random double between 0 (inclusive) and Double.MAX_VALUE (1.7976931348623157E308 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.

      If the bounds are equal, returns the common bound. If startInclusive is finite and endExclusive is positive infinity, returns Double.MAX_VALUE.

      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 - Thrown 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.

      If the bounds are equal, returns the common bound. If startInclusive is finite and endExclusive is positive infinity, returns Float.MAX_VALUE.

      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 - Thrown if startInclusive > endExclusive or if startInclusive is negative.
      Since:
      3.16.0
    • randomInt

      public int randomInt()
      Generates a random int between 0 (inclusive) and Integer.MAX_VALUE (2147483647 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 - Thrown 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 (9223372036854775807L, exclusive).
      Returns:
      The random long.
      Since:
      3.16.0
      See Also:
    • 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 - Thrown if startInclusive > endExclusive or if startInclusive is negative.
      Since:
      3.16.0
    • toString

      public String toString()
      Overrides:
      toString in class Object