RandomUtils (Apache Commons Lang 3.20.0 API)
Description: declaration: package: org.apache.commons.lang3, class: RandomUtils

# 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:
  - `secure()`
  - `secureStrong()`
  - `insecure()`
  - `SecureRandom()`
  - `SecureRandom.getInstanceStrong()`
  - `ThreadLocalRandom.current()`
  - `RandomStringUtils`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `RandomUtils()`
  Deprecated.
  TODO Make private in 4.0.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `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.
  `static boolean`
  `nextBoolean()`
  Deprecated.
  Use `secure()`, `secureStrong()`, or `insecure()`.
  `static byte[]`
  `nextBytes(int count)`
  Deprecated.
  Use `secure()`, `secureStrong()`, or `insecure()`.
  `static double`
  `nextDouble()`
  Deprecated.
  Use `secure()`, `secureStrong()`, or `insecure()`.
  `static double`
  `nextDouble(double startInclusive, double endExclusive)`
  Deprecated.
  Use `secure()`, `secureStrong()`, or `insecure()`.
  `static float`
  `nextFloat()`
  Deprecated.
  Use `secure()`, `secureStrong()`, or `insecure()`.
  `static float`
  `nextFloat(float startInclusive, float endExclusive)`
  Deprecated.
  Use `secure()`, `secureStrong()`, or `insecure()`.
  `static int`
  `nextInt()`
  Deprecated.
  Use `secure()`, `secureStrong()`, or `insecure()`.
  `static int`
  `nextInt(int startInclusive, int endExclusive)`
  Deprecated.
  Use `secure()`, `secureStrong()`, or `insecure()`.
  `static long`
  `nextLong()`
  Deprecated.
  Use `secure()`, `secureStrong()`, or `insecure()`.
  `static long`
  `nextLong(long startInclusive, long endExclusive)`
  Deprecated.
  Use `secure()`, `secureStrong()`, or `insecure()`.
  `boolean`
  `randomBoolean()`
  Generates a random boolean value.
  `byte[]`
  `randomBytes(int count)`
  Generates an array of random bytes.
  `double`
  `randomDouble()`
  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`
  `randomFloat()`
  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`
  `randomInt()`
  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`
  `randomLong()`
  Generates a random long between 0 (inclusive) and Long.MAX_VALUE (exclusive).
  `long`
  `randomLong(long startInclusive, long endExclusive)`
  Generates a random long within the specified range.
  `static RandomUtils`
  `secure()`
  Gets the singleton instance based on `SecureRandom()` which uses an algorithms/providers specified in the `securerandom.strongAlgorithms` `Security` property.
  `static RandomUtils`
  `secureStrong()`
  Gets the singleton instance based on `SecureRandom.getInstanceStrong()` which uses an algorithms/providers specified in the `securerandom.strongAlgorithms` `Security` property.
  `String`
  `toString()`

  ### Methods inherited from class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- ## 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; 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:
      `IllegalArgumentException` - if `count` is negative.

  - ### nextDouble

    @Deprecated public static double nextDouble()
    Deprecated.
    Use `secure()`, `secureStrong()`, or `insecure()`.
    Generates a random double between 0 (inclusive) and Double.MAX_VALUE (exclusive).
    Returns:
      the random double.
    Since:
      3.5
    See Also:
      - `nextDouble(double, double)`

  - ### 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:
      `IllegalArgumentException` - if `startInclusive > endExclusive` or if `startInclusive` is negative.

  - ### nextFloat

    @Deprecated public static float nextFloat()
    Deprecated.
    Use `secure()`, `secureStrong()`, or `insecure()`.
    Generates a random float between 0 (inclusive) and Float.MAX_VALUE (exclusive).
    Returns:
      the random float.
    Since:
      3.5
    See Also:
      - `nextFloat(float, float)`

  - ### 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:
      `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:
      `IllegalArgumentException` - if `startInclusive > endExclusive` or if `startInclusive` is negative.

  - ### nextLong

    @Deprecated public static long nextLong()
    Deprecated.
    Use `secure()`, `secureStrong()`, or `insecure()`.
    Generates a random long between 0 (inclusive) and Long.MAX_VALUE (exclusive).
    Returns:
      the random long.
    Since:
      3.5
    See Also:
      - `nextLong(long, long)`

  - ### 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:
      `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()`

  - ### 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()`

  - ### 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(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:
      `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:
      `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:
      `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

    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`