org.apache.commons.lang3

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 and Description
RandomUtils() Deprecated. TODO Make private in 4.0.

Method Summary

Modifier and Type	Method and 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 java.lang.Object

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

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.

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:

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