Top Description Fields Constructors Methods
org.apache.commons.lang3

public Class RandomUtils

extends Object
Class Inheritance
Imports
java.security.NoSuchAlgorithmException, .SecureRandom, .Security, java.util.Random, java.util.concurrent.ThreadLocalRandom, java.util.function.Supplier, org.apache.commons.lang3.exception.UncheckedException
Supplements the standard Random class.

Use secure() to get the singleton instance based on SecureRandom#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#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(), SecureRandom#getInstanceStrong(), ThreadLocalRandom#current(), RandomStringUtils

Field Summary

Modifier and TypeField and Description
private static RandomUtils
INSECURE

private final Supplier<Random>
random

private static RandomUtils
SECURE

private static final ThreadLocal<SecureRandom>
SECURE_RANDOM_STRONG

private static RandomUtils
SECURE_STRONG

private static final Supplier<Random>
SECURE_STRONG_SUPPLIER

Constructor Summary

AccessConstructor and Description
public
RandomUtils()
Deprecated TODO Make private in 4.0.

RandomUtils instances should NOT be constructed in standard programming.

private
RandomUtils(final Supplier<Random> random)

Method Summary

Modifier and TypeMethod and Description
public static RandomUtils

Returns:

the singleton instance based on ThreadLocalRandom#current().
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.

public static boolean

Returns:

the random boolean.
nextBoolean()
Deprecated Use secure(), secureStrong(), or insecure().

Generates a random boolean value.

public static byte[]

Returns:

the random byte array.
nextBytes(final int
the size of the returned array.
count)
Deprecated Use secure(), secureStrong(), or insecure().

Generates an array of random bytes.

public static double

Returns:

the random double.
nextDouble()
Deprecated Use secure(), secureStrong(), or insecure().

Generates a random double between 0 (inclusive) and Double.MAX_VALUE (exclusive).

public static double

Returns:

the random double.
nextDouble(final double
the smallest value that can be returned, must be non-negative.
startInclusive, final double
the upper bound (not included).
endExclusive)
Deprecated Use secure(), secureStrong(), or insecure().

Generates a random double within the specified range.

public static float

Returns:

the random float.
nextFloat()
Deprecated Use secure(), secureStrong(), or insecure().

Generates a random float between 0 (inclusive) and Float.MAX_VALUE (exclusive).

public static float

Returns:

the random float
nextFloat(final float
the smallest value that can be returned, must be non-negative.
startInclusive, final float
the upper bound (not included).
endExclusive)
Deprecated Use secure(), secureStrong(), or insecure().

Generates a random float within the specified range.

public static int

Returns:

the random integer.
nextInt()
Deprecated Use secure(), secureStrong(), or insecure().

Generates a random int between 0 (inclusive) and Integer.MAX_VALUE (exclusive).

public static int

Returns:

the random integer.
nextInt(final int
the smallest value that can be returned, must be non-negative.
startInclusive, final int
the upper bound (not included).
endExclusive)
Deprecated Use secure(), secureStrong(), or insecure().

Generates a random integer within the specified range.

public static long

Returns:

the random long.
nextLong()
Deprecated Use secure(), secureStrong(), or insecure().

Generates a random long between 0 (inclusive) and Long.MAX_VALUE (exclusive).

public static long

Returns:

the random long.
nextLong(final long
the smallest value that can be returned, must be non-negative.
startInclusive, final long
the upper bound (not included).
endExclusive)
Deprecated Use secure(), secureStrong(), or insecure().

Generates a random long within the specified range.

pack-priv Random
random()

public boolean

Returns:

the random boolean.
randomBoolean()

Generates a random boolean value.

public byte[]

Returns:

the random byte array.
randomBytes(final int
the size of the returned array.
count)

Generates an array of random bytes.

public double

Returns:

the random double.
randomDouble()

Generates a random double between 0 (inclusive) and Double.MAX_VALUE (exclusive).

public double

Returns:

the random double
randomDouble(final double
the smallest value that can be returned, must be non-negative.
startInclusive, final double
the upper bound (not included).
endExclusive)

Generates a random double within the specified range.

public float

Returns:

the random float.
randomFloat()

Generates a random float between 0 (inclusive) and Float.MAX_VALUE (exclusive).

public float

Returns:

the random float.
randomFloat(final float
the smallest value that can be returned, must be non-negative.
startInclusive, final float
the upper bound (not included).
endExclusive)

Generates a random float within the specified range.

public int

Returns:

the random integer.
randomInt()

Generates a random int between 0 (inclusive) and Integer.MAX_VALUE (exclusive).

public int

Returns:

the random integer.
randomInt(final int
the smallest value that can be returned, must be non-negative.
startInclusive, final int
the upper bound (not included).
endExclusive)

Generates a random integer within the specified range.

public long

Returns:

the random long.
randomLong()

Generates a random long between 0 (inclusive) and Long.MAX_VALUE (exclusive).

private long

Returns:

a random long value between 0 (inclusive) and n (exclusive).
randomLong(final long
Bound on the random number to be returned. Must be positive.
n)

Generates a long value between 0 (inclusive) and the specified value (exclusive).

public long

Returns:

the random long.
randomLong(final long
the smallest value that can be returned, must be non-negative.
startInclusive, final long
the upper bound (not included).
endExclusive)

Generates a random long within the specified range.

public static RandomUtils

Returns:

the singleton instance based on SecureRandom#SecureRandom().
secure()

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

pack-priv static SecureRandom
secureRandom()

public static RandomUtils

Returns:

the singleton instance based on SecureRandom#getInstanceStrong().
secureStrong()

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

public String
toString()

Overrides java.lang.Object.toString.

Returns a string representation of the object.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAllwaitwaitwait

Field Detail

INSECUREback to summary
private static RandomUtils INSECURE
randomback to summary
private final Supplier<Random> random
SECUREback to summary
private static RandomUtils SECURE
SECURE_RANDOM_STRONGback to summary
private static final ThreadLocal<SecureRandom> SECURE_RANDOM_STRONG
SECURE_STRONGback to summary
private static RandomUtils SECURE_STRONG
SECURE_STRONG_SUPPLIERback to summary
private static final Supplier<Random> SECURE_STRONG_SUPPLIER

Constructor Detail

RandomUtilsback to summary
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.

Annotations
@Deprecated
RandomUtilsback to summary
private RandomUtils(final Supplier<Random> random)

Method Detail

insecureback to summary
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:RandomUtils

the singleton instance based on ThreadLocalRandom#current().

Since
3.17.0
See Also
ThreadLocalRandom#current(), secure()
nextBooleanback to summary
public static boolean nextBoolean()

Deprecated

Use secure(), secureStrong(), or insecure().

Generates a random boolean value.

Returns:boolean

the random boolean.

Annotations
@Deprecated
Since
3.5
nextBytesback to summary
public static byte[] nextBytes(final int count)

Deprecated

Use secure(), secureStrong(), or insecure().

Generates an array of random bytes.

Parameters
count:int

the size of the returned array.

Returns:byte[]

the random byte array.

Annotations
@Deprecated
Exceptions
IllegalArgumentException:
if count is negative.
nextDoubleback to summary
public static double nextDouble()

Deprecated

Use secure(), secureStrong(), or insecure().

Generates a random double between 0 (inclusive) and Double.MAX_VALUE (exclusive).

Returns:double

the random double.

Annotations
@Deprecated
Since
3.5
See Also
nextDouble(double, double)
nextDoubleback to summary
public static double nextDouble(final double startInclusive, final double endExclusive)

Deprecated

Use secure(), secureStrong(), or insecure().

Generates a random double within the specified range.

Parameters
startInclusive:double

the smallest value that can be returned, must be non-negative.

endExclusive:double

the upper bound (not included).

Returns:double

the random double.

Annotations
@Deprecated
Exceptions
IllegalArgumentException:
if startInclusive > endExclusive or if startInclusive is negative.
nextFloatback to summary
public static float nextFloat()

Deprecated

Use secure(), secureStrong(), or insecure().

Generates a random float between 0 (inclusive) and Float.MAX_VALUE (exclusive).

Returns:float

the random float.

Annotations
@Deprecated
Since
3.5
See Also
nextFloat(float, float)
nextFloatback to summary
public static float nextFloat(final float startInclusive, final float endExclusive)

Deprecated

Use secure(), secureStrong(), or insecure().

Generates a random float within the specified range.

Parameters
startInclusive:float

the smallest value that can be returned, must be non-negative.

endExclusive:float

the upper bound (not included).

Returns:float

the random float

Annotations
@Deprecated
Exceptions
IllegalArgumentException:
if startInclusive > endExclusive or if startInclusive is negative.
nextIntback to summary
public static int nextInt()

Deprecated

Use secure(), secureStrong(), or insecure().

Generates a random int between 0 (inclusive) and Integer.MAX_VALUE (exclusive).

Returns:int

the random integer.

Annotations
@Deprecated
Since
3.5
See Also
nextInt(int, int)
nextIntback to summary
public static int nextInt(final int startInclusive, final int endExclusive)

Deprecated

Use secure(), secureStrong(), or insecure().

Generates a random integer within the specified range.

Parameters
startInclusive:int

the smallest value that can be returned, must be non-negative.

endExclusive:int

the upper bound (not included).

Returns:int

the random integer.

Annotations
@Deprecated
Exceptions
IllegalArgumentException:
if startInclusive > endExclusive or if startInclusive is negative.
nextLongback to summary
public static long nextLong()

Deprecated

Use secure(), secureStrong(), or insecure().

Generates a random long between 0 (inclusive) and Long.MAX_VALUE (exclusive).

Returns:long

the random long.

Annotations
@Deprecated
Since
3.5
See Also
nextLong(long, long)
nextLongback to summary
public static long nextLong(final long startInclusive, final long endExclusive)

Deprecated

Use secure(), secureStrong(), or insecure().

Generates a random long within the specified range.

Parameters
startInclusive:long

the smallest value that can be returned, must be non-negative.

endExclusive:long

the upper bound (not included).

Returns:long

the random long.

Annotations
@Deprecated
Exceptions
IllegalArgumentException:
if startInclusive > endExclusive or if startInclusive is negative.
randomback to summary
pack-priv Random random()
randomBooleanback to summary
public boolean randomBoolean()

Generates a random boolean value.

Returns:boolean

the random boolean.

Since
3.16.0
randomBytesback to summary
public byte[] randomBytes(final int count)

Generates an array of random bytes.

Parameters
count:int

the size of the returned array.

Returns:byte[]

the random byte array.

Exceptions
IllegalArgumentException:
if count is negative
Since
3.16.0
randomDoubleback to summary
public double randomDouble()

Generates a random double between 0 (inclusive) and Double.MAX_VALUE (exclusive).

Returns:double

the random double.

Since
3.16.0
See Also
randomDouble(double, double)
randomDoubleback to summary
public double randomDouble(final double startInclusive, final double endExclusive)

Generates a random double within the specified range.

Parameters
startInclusive:double

the smallest value that can be returned, must be non-negative.

endExclusive:double

the upper bound (not included).

Returns:double

the random double

Exceptions
IllegalArgumentException:
if startInclusive > endExclusive or if startInclusive is negative.
Since
3.16.0
randomFloatback to summary
public float randomFloat()

Generates a random float between 0 (inclusive) and Float.MAX_VALUE (exclusive).

Returns:float

the random float.

Since
3.16.0
See Also
randomFloat(float, float)
randomFloatback to summary
public float randomFloat(final float startInclusive, final float endExclusive)

Generates a random float within the specified range.

Parameters
startInclusive:float

the smallest value that can be returned, must be non-negative.

endExclusive:float

the upper bound (not included).

Returns:float

the random float.

Exceptions
IllegalArgumentException:
if startInclusive > endExclusive or if startInclusive is negative.
randomIntback to summary
public int randomInt()

Generates a random int between 0 (inclusive) and Integer.MAX_VALUE (exclusive).

Returns:int

the random integer.

Since
3.16.0
See Also
randomInt(int, int)
randomIntback to summary
public int randomInt(final int startInclusive, final int endExclusive)

Generates a random integer within the specified range.

Parameters
startInclusive:int

the smallest value that can be returned, must be non-negative.

endExclusive:int

the upper bound (not included).

Returns:int

the random integer.

Exceptions
IllegalArgumentException:
if startInclusive > endExclusive or if startInclusive is negative.
Since
3.16.0
randomLongback to summary
public long randomLong()

Generates a random long between 0 (inclusive) and Long.MAX_VALUE (exclusive).

Returns:long

the random long.

Since
3.16.0
See Also
randomLong(long, long)
randomLongback to summary
private long randomLong(final long n)

Generates a long value between 0 (inclusive) and the specified value (exclusive).

Parameters
n:long

Bound on the random number to be returned. Must be positive.

Returns:long

a random long value between 0 (inclusive) and n (exclusive).

randomLongback to summary
public long randomLong(final long startInclusive, final long endExclusive)

Generates a random long within the specified range.

Parameters
startInclusive:long

the smallest value that can be returned, must be non-negative.

endExclusive:long

the upper bound (not included).

Returns:long

the random long.

Exceptions
IllegalArgumentException:
if startInclusive > endExclusive or if startInclusive is negative.
Since
3.16.0
secureback to summary
public static RandomUtils secure()

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

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

Returns:RandomUtils

the singleton instance based on SecureRandom#SecureRandom().

Since
3.16.0
See Also
SecureRandom#SecureRandom()
secureRandomback to summary
pack-priv static SecureRandom secureRandom()
secureStrongback to summary
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:RandomUtils

the singleton instance based on SecureRandom#getInstanceStrong().

Since
3.17.0
See Also
SecureRandom#getInstanceStrong()
toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object. Satisfying this method's contract implies a non-null result must be returned.

Annotations
@Override