- All Implemented Interfaces:
Serializable,RandomGenerator
Random
generator used by the Math class,
a ThreadLocalRandom is initialized
with an internally generated seed that may not otherwise be
modified. When applicable, use of ThreadLocalRandom rather
than shared Random objects in concurrent programs will
typically encounter much less overhead and contention. Use of
ThreadLocalRandom is particularly appropriate when multiple
tasks (for example, each a ForkJoinTask) use random numbers
in parallel in thread pools.
Usages of this class should typically be of the form:
ThreadLocalRandom.current().nextX(...) (where
X is Int, Long, etc).
When all usages are of this form, it is never possible to
accidentally share a ThreadLocalRandom across multiple threads.
This class also provides additional commonly used bounded random generation methods.
Instances of ThreadLocalRandom are not cryptographically
secure. Consider instead using SecureRandom
in security-sensitive applications. Additionally,
default-constructed instances do not use a cryptographically random
seed unless the system property
java.util.secureRandomSeed is set to true.
- Since:
- 1.7
- See Also:
-
Nested Class Summary
Nested classes/interfaces declared in interface java.util.random.RandomGenerator
RandomGenerator.ArbitrarilyJumpableGenerator, RandomGenerator.JumpableGenerator, RandomGenerator.LeapableGenerator, RandomGenerator.SplittableGenerator, RandomGenerator.StreamableGenerator -
Method Summary
Modifier and TypeMethodDescriptionstatic ThreadLocalRandomcurrent()Returns the current thread'sThreadLocalRandomobject.doubles()Returns an effectively unlimited stream of pseudorandomdoublevalues, each between zero (inclusive) and one (exclusive).doubles(double randomNumberOrigin, double randomNumberBound) Returns an effectively unlimited stream of pseudorandomdoublevalues, each conforming to the given origin (inclusive) and bound (exclusive).doubles(long streamSize) Returns a stream producing the givenstreamSizenumber of pseudorandomdoublevalues, each between zero (inclusive) and one (exclusive).doubles(long streamSize, double randomNumberOrigin, double randomNumberBound) Returns a stream producing the givenstreamSizenumber of pseudorandomdoublevalues, each conforming to the given origin (inclusive) and bound (exclusive).ints()Returns an effectively unlimited stream of pseudorandomintvalues.ints(int randomNumberOrigin, int randomNumberBound) Returns an effectively unlimited stream of pseudorandomintvalues, each conforming to the given origin (inclusive) and bound (exclusive).ints(long streamSize) Returns a stream producing the givenstreamSizenumber of pseudorandomintvalues.ints(long streamSize, int randomNumberOrigin, int randomNumberBound) Returns a stream producing the givenstreamSizenumber of pseudorandomintvalues, each conforming to the given origin (inclusive) and bound (exclusive).longs()Returns an effectively unlimited stream of pseudorandomlongvalues.longs(long streamSize) Returns a stream producing the givenstreamSizenumber of pseudorandomlongvalues.longs(long randomNumberOrigin, long randomNumberBound) Returns an effectively unlimited stream of pseudorandomlongvalues, each conforming to the given origin (inclusive) and bound (exclusive).longs(long streamSize, long randomNumberOrigin, long randomNumberBound) Returns a stream producing the givenstreamSizenumber of pseudorandomlong, each conforming to the given origin (inclusive) and bound (exclusive).protected intnext(int bits) Generates a pseudorandom number with the indicated number of low-order bits.doublenextDouble(double bound) Returns a pseudorandomly chosendoublevalue between zero (inclusive) and the specified bound (exclusive).doublenextDouble(double origin, double bound) Returns a pseudorandomly chosendoublevalue between the specified origin (inclusive) and the specified bound (exclusive).floatnextFloat(float bound) Returns a pseudorandomly chosenfloatvalue between zero (inclusive) and the specified bound (exclusive).floatnextFloat(float origin, float bound) Returns a pseudorandomly chosenfloatvalue between the specified origin (inclusive) and the specified bound (exclusive).intnextInt(int bound) Returns a pseudorandom, uniformly distributedintvalue between 0 (inclusive) and the specified value (exclusive), drawn from this random number generator's sequence.intnextInt(int origin, int bound) Returns a pseudorandomly chosenintvalue between the specified origin (inclusive) and the specified bound (exclusive).longnextLong(long bound) Returns a pseudorandomly chosenlongvalue between zero (inclusive) and the specified bound (exclusive).longnextLong(long origin, long bound) Returns a pseudorandomly chosenlongvalue between the specified origin (inclusive) and the specified bound (exclusive).voidsetSeed(long seed) ThrowsUnsupportedOperationException.Methods declared in class java.util.Random
nextBoolean, nextBytes, nextDouble, nextFloat, nextGaussian, nextInt, nextLongMethods declared in class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, waitMethods declared in interface java.util.random.RandomGenerator
isDeprecated, nextExponential, nextGaussian
-
Method Details
-
current
Returns the current thread'sThreadLocalRandomobject. Methods of this object should be called only by the current thread, not by other threads.- Returns:
- the current thread's
ThreadLocalRandom
-
setSeed
public void setSeed(long seed) ThrowsUnsupportedOperationException. Setting seeds in this generator is not supported.- Overrides:
setSeedin classRandom- Parameters:
seed- the initial seed- Throws:
UnsupportedOperationException- always
-
next
protected int next(int bits) Generates a pseudorandom number with the indicated number of low-order bits. Because this class has no subclasses, this method cannot be invoked or overridden. -
nextInt
public int nextInt(int bound) Returns a pseudorandom, uniformly distributedintvalue between 0 (inclusive) and the specified value (exclusive), drawn from this random number generator's sequence. The general contract ofnextIntis that oneintvalue in the specified range is pseudorandomly generated and returned. Allboundpossibleintvalues are produced with (approximately) equal probability.- Specified by:
nextIntin interfaceRandomGenerator- Overrides:
nextIntin classRandom- Parameters:
bound- the upper bound (exclusive). Must be positive.- Returns:
- the next pseudorandom, uniformly distributed
intvalue between zero (inclusive) andbound(exclusive) from this random number generator's sequence - Throws:
IllegalArgumentException- if bound is not positive
-
nextInt
public int nextInt(int origin, int bound) Returns a pseudorandomly chosenintvalue between the specified origin (inclusive) and the specified bound (exclusive).- Parameters:
origin- the least value that can be returnedbound- the upper bound (exclusive) for the returned value- Returns:
- a pseudorandomly chosen
intvalue between the origin (inclusive) and the bound (exclusive) - Throws:
IllegalArgumentException- iforiginis greater than or equal tobound
-
nextLong
public long nextLong(long bound) Returns a pseudorandomly chosenlongvalue between zero (inclusive) and the specified bound (exclusive).- Parameters:
bound- the upper bound (exclusive) for the returned value. Must be positive.- Returns:
- a pseudorandomly chosen
longvalue between zero (inclusive) and the bound (exclusive) - Throws:
IllegalArgumentException- ifboundis not positive
-
nextLong
public long nextLong(long origin, long bound) Returns a pseudorandomly chosenlongvalue between the specified origin (inclusive) and the specified bound (exclusive).- Parameters:
origin- the least value that can be returnedbound- the upper bound (exclusive) for the returned value- Returns:
- a pseudorandomly chosen
longvalue between the origin (inclusive) and the bound (exclusive) - Throws:
IllegalArgumentException- iforiginis greater than or equal tobound
-
nextFloat
public float nextFloat(float bound) Returns a pseudorandomly chosenfloatvalue between zero (inclusive) and the specified bound (exclusive).- Implementation Note:
- Parameters:
bound- the upper bound (exclusive) for the returned value. Must be positive and finite- Returns:
- a pseudorandomly chosen
floatvalue between zero (inclusive) and the bound (exclusive) - Throws:
IllegalArgumentException- ifboundis not both positive and finite
-
nextFloat
public float nextFloat(float origin, float bound) Returns a pseudorandomly chosenfloatvalue between the specified origin (inclusive) and the specified bound (exclusive).- Implementation Note:
- Parameters:
origin- the least value that can be returnedbound- the upper bound (exclusive)- Returns:
- a pseudorandomly chosen
floatvalue between the origin (inclusive) and the bound (exclusive) - Throws:
IllegalArgumentException- iforiginis not finite, orboundis not finite, ororiginis greater than or equal tobound
-
nextDouble
public double nextDouble(double bound) Returns a pseudorandomly chosendoublevalue between zero (inclusive) and the specified bound (exclusive).- Implementation Note:
- Parameters:
bound- the upper bound (exclusive) for the returned value. Must be positive and finite- Returns:
- a pseudorandomly chosen
doublevalue between zero (inclusive) and the bound (exclusive) - Throws:
IllegalArgumentException- ifboundis not both positive and finite
-
nextDouble
public double nextDouble(double origin, double bound) Returns a pseudorandomly chosendoublevalue between the specified origin (inclusive) and the specified bound (exclusive).- Implementation Note:
- Parameters:
origin- the least value that can be returnedbound- the upper bound (exclusive) for the returned value- Returns:
- a pseudorandomly chosen
doublevalue between the origin (inclusive) and the bound (exclusive) - Throws:
IllegalArgumentException- iforiginis not finite, orboundis not finite, ororiginis greater than or equal tobound
-
ints
Returns a stream producing the givenstreamSizenumber of pseudorandomintvalues.A pseudorandom
intvalue is generated as if it's the result of calling the methodRandom.nextInt().- Specified by:
intsin interfaceRandomGenerator- Overrides:
intsin classRandom- Parameters:
streamSize- the number of values to generate- Returns:
- a stream of pseudorandom
intvalues - Throws:
IllegalArgumentException- ifstreamSizeis less than zero- Since:
- 1.8
-
ints
Returns an effectively unlimited stream of pseudorandomintvalues.A pseudorandom
intvalue is generated as if it's the result of calling the methodRandom.nextInt().- Specified by:
intsin interfaceRandomGenerator- Overrides:
intsin classRandom- Implementation Note:
- This method is implemented to be equivalent to
ints(Long.MAX_VALUE). - Returns:
- a stream of pseudorandom
intvalues - Since:
- 1.8
-
ints
Returns a stream producing the givenstreamSizenumber of pseudorandomintvalues, each conforming to the given origin (inclusive) and bound (exclusive).A pseudorandom
intvalue is generated as if it's the result of calling the following method with the origin and bound:int nextInt(int origin, int bound) { int n = bound - origin; if (n > 0) { return nextInt(n) + origin; } else { // range not representable as int int r; do { r = nextInt(); } while (r < origin || r >= bound); return r; } }- Specified by:
intsin interfaceRandomGenerator- Overrides:
intsin classRandom- Parameters:
streamSize- the number of values to generaterandomNumberOrigin- the origin (inclusive) of each random valuerandomNumberBound- the bound (exclusive) of each random value- Returns:
- a stream of pseudorandom
intvalues, each with the given origin (inclusive) and bound (exclusive) - Throws:
IllegalArgumentException- ifstreamSizeis less than zero, orrandomNumberOriginis greater than or equal torandomNumberBound- Since:
- 1.8
-
ints
Returns an effectively unlimited stream of pseudorandomintvalues, each conforming to the given origin (inclusive) and bound (exclusive).A pseudorandom
intvalue is generated as if it's the result of calling the following method with the origin and bound:int nextInt(int origin, int bound) { int n = bound - origin; if (n > 0) { return nextInt(n) + origin; } else { // range not representable as int int r; do { r = nextInt(); } while (r < origin || r >= bound); return r; } }- Specified by:
intsin interfaceRandomGenerator- Overrides:
intsin classRandom- Implementation Note:
- This method is implemented to be equivalent to
ints(Long.MAX_VALUE, randomNumberOrigin, randomNumberBound). - Parameters:
randomNumberOrigin- the origin (inclusive) of each random valuerandomNumberBound- the bound (exclusive) of each random value- Returns:
- a stream of pseudorandom
intvalues, each with the given origin (inclusive) and bound (exclusive) - Throws:
IllegalArgumentException- ifrandomNumberOriginis greater than or equal torandomNumberBound- Since:
- 1.8
-
longs
Returns a stream producing the givenstreamSizenumber of pseudorandomlongvalues.A pseudorandom
longvalue is generated as if it's the result of calling the methodRandom.nextLong().- Specified by:
longsin interfaceRandomGenerator- Overrides:
longsin classRandom- Parameters:
streamSize- the number of values to generate- Returns:
- a stream of pseudorandom
longvalues - Throws:
IllegalArgumentException- ifstreamSizeis less than zero- Since:
- 1.8
-
longs
Returns an effectively unlimited stream of pseudorandomlongvalues.A pseudorandom
longvalue is generated as if it's the result of calling the methodRandom.nextLong().- Specified by:
longsin interfaceRandomGenerator- Overrides:
longsin classRandom- Implementation Note:
- This method is implemented to be equivalent to
longs(Long.MAX_VALUE). - Returns:
- a stream of pseudorandom
longvalues - Since:
- 1.8
-
longs
Returns a stream producing the givenstreamSizenumber of pseudorandomlong, each conforming to the given origin (inclusive) and bound (exclusive).A pseudorandom
longvalue is generated as if it's the result of calling the following method with the origin and bound:long nextLong(long origin, long bound) { long r = nextLong(); long n = bound - origin, m = n - 1; if ((n & m) == 0L) // power of two r = (r & m) + origin; else if (n > 0L) { // reject over-represented candidates for (long u = r >>> 1; // ensure nonnegative u + m - (r = u % n) < 0L; // rejection check u = nextLong() >>> 1) // retry ; r += origin; } else { // range not representable as long while (r < origin || r >= bound) r = nextLong(); } return r; }- Specified by:
longsin interfaceRandomGenerator- Overrides:
longsin classRandom- Parameters:
streamSize- the number of values to generaterandomNumberOrigin- the origin (inclusive) of each random valuerandomNumberBound- the bound (exclusive) of each random value- Returns:
- a stream of pseudorandom
longvalues, each with the given origin (inclusive) and bound (exclusive) - Throws:
IllegalArgumentException- ifstreamSizeis less than zero, orrandomNumberOriginis greater than or equal torandomNumberBound- Since:
- 1.8
-
longs
Returns an effectively unlimited stream of pseudorandomlongvalues, each conforming to the given origin (inclusive) and bound (exclusive).A pseudorandom
longvalue is generated as if it's the result of calling the following method with the origin and bound:long nextLong(long origin, long bound) { long r = nextLong(); long n = bound - origin, m = n - 1; if ((n & m) == 0L) // power of two r = (r & m) + origin; else if (n > 0L) { // reject over-represented candidates for (long u = r >>> 1; // ensure nonnegative u + m - (r = u % n) < 0L; // rejection check u = nextLong() >>> 1) // retry ; r += origin; } else { // range not representable as long while (r < origin || r >= bound) r = nextLong(); } return r; }- Specified by:
longsin interfaceRandomGenerator- Overrides:
longsin classRandom- Implementation Note:
- This method is implemented to be equivalent to
longs(Long.MAX_VALUE, randomNumberOrigin, randomNumberBound). - Parameters:
randomNumberOrigin- the origin (inclusive) of each random valuerandomNumberBound- the bound (exclusive) of each random value- Returns:
- a stream of pseudorandom
longvalues, each with the given origin (inclusive) and bound (exclusive) - Throws:
IllegalArgumentException- ifrandomNumberOriginis greater than or equal torandomNumberBound- Since:
- 1.8
-
doubles
Returns a stream producing the givenstreamSizenumber of pseudorandomdoublevalues, each between zero (inclusive) and one (exclusive).A pseudorandom
doublevalue is generated as if it's the result of calling the methodRandom.nextDouble().- Specified by:
doublesin interfaceRandomGenerator- Overrides:
doublesin classRandom- Parameters:
streamSize- the number of values to generate- Returns:
- a stream of
doublevalues - Throws:
IllegalArgumentException- ifstreamSizeis less than zero- Since:
- 1.8
-
doubles
Returns an effectively unlimited stream of pseudorandomdoublevalues, each between zero (inclusive) and one (exclusive).A pseudorandom
doublevalue is generated as if it's the result of calling the methodRandom.nextDouble().- Specified by:
doublesin interfaceRandomGenerator- Overrides:
doublesin classRandom- Implementation Note:
- This method is implemented to be equivalent to
doubles(Long.MAX_VALUE). - Returns:
- a stream of pseudorandom
doublevalues - Since:
- 1.8
-
doubles
Returns a stream producing the givenstreamSizenumber of pseudorandomdoublevalues, each conforming to the given origin (inclusive) and bound (exclusive).A pseudorandom
doublevalue is generated as if it's the result of calling the following method with the origin and bound:double nextDouble(double origin, double bound) { double r = nextDouble(); r = r * (bound - origin) + origin; if (r >= bound) // correct for rounding r = Math.nextDown(bound); return r; }- Specified by:
doublesin interfaceRandomGenerator- Overrides:
doublesin classRandom- Parameters:
streamSize- the number of values to generaterandomNumberOrigin- the origin (inclusive) of each random valuerandomNumberBound- the bound (exclusive) of each random value- Returns:
- a stream of pseudorandom
doublevalues, each with the given origin (inclusive) and bound (exclusive) - Throws:
IllegalArgumentException- ifstreamSizeis less than zero, orrandomNumberOriginis not finite, orrandomNumberBoundis not finite, orrandomNumberOriginis greater than or equal torandomNumberBound- Since:
- 1.8
-
doubles
Returns an effectively unlimited stream of pseudorandomdoublevalues, each conforming to the given origin (inclusive) and bound (exclusive).A pseudorandom
doublevalue is generated as if it's the result of calling the following method with the origin and bound:double nextDouble(double origin, double bound) { double r = nextDouble(); r = r * (bound - origin) + origin; if (r >= bound) // correct for rounding r = Math.nextDown(bound); return r; }- Specified by:
doublesin interfaceRandomGenerator- Overrides:
doublesin classRandom- Implementation Note:
- This method is implemented to be equivalent to
doubles(Long.MAX_VALUE, randomNumberOrigin, randomNumberBound). - Parameters:
randomNumberOrigin- the origin (inclusive) of each random valuerandomNumberBound- the bound (exclusive) of each random value- Returns:
- a stream of pseudorandom
doublevalues, each with the given origin (inclusive) and bound (exclusive) - Throws:
IllegalArgumentException- ifrandomNumberOriginis greater than or equal torandomNumberBound- Since:
- 1.8
-