Added in API level 35

Summary: Methods | Inherited Methods

RandomGeneratorFactory

public final class RandomGeneratorFactory
extends Object

java.lang.Object
↳	java.util.random.RandomGeneratorFactory<T extends java.util.random.RandomGenerator>

---

This is a factory class for generating multiple random number generators of a specific algorithm. RandomGeneratorFactory also provides methods for selecting random number generator algorithms. A specific RandomGeneratorFactory can be located by using the RandomGeneratorFactory.of(String) method, where the argument string is the name of the algorithm required. The method RandomGeneratorFactory.all() produces a non-empty Stream of all available RandomGeneratorFactorys that can be searched to locate a RandomGeneratorFactory suitable to the task. There are three methods for constructing a RandomGenerator instance, depending on the type of initial seed required. RandomGeneratorFactory.create(long) is used for long seed construction, RandomGeneratorFactory.create(byte[]) is used for byte[] seed construction, and RandomGeneratorFactory.create() is used for random seed construction. Example;

RandomGeneratorFactory<RandomGenerator> factory = RandomGeneratorFactory.of("Random");

     for (int i = 0; i < 10; i++) {
         new Thread(() -> {
             RandomGenerator random = factory.create(100L);
             System.out.println(random.nextDouble());
         }).start();
     }
 

RandomGeneratorFactory also provides methods describing the attributes (or properties) of a generator and can be used to select random number generator algorithms. These methods are typically used in conjunction with RandomGeneratorFactory.all(). In this example, the code locates the RandomGeneratorFactory that produces RandomGenerators with the highest number of state bits.

RandomGeneratorFactory<RandomGenerator> best = RandomGeneratorFactory.all()
         .sorted(Comparator.comparingInt(RandomGenerator::stateBits).reversed())
         .findFirst()
         .orElse(RandomGeneratorFactory.of("Random"));
     System.out.println(best.name() + " in " + best.group() + " was selected");

     RandomGenerator rng = best.create();
     System.out.println(rng.nextLong());
 

See also:

• java.util.random

Summary

Public methods
static Stream<RandomGeneratorFactory<RandomGenerator>>	all() Returns a non-empty stream of available RandomGeneratorFactory(s).
T	create(byte[] seed) Create an instance of RandomGenerator based on algorithm chosen providing a starting byte[] seed.
T	create(long seed) Create an instance of RandomGenerator based on algorithm chosen providing a starting long seed.
T	create() Create an instance of RandomGenerator based on algorithm chosen.
int	equidistribution() Returns the equidistribution of the algorithm.
static RandomGeneratorFactory<RandomGenerator>	getDefault() Returns a RandomGeneratorFactory meeting the minimal requirement of having an algorithm whose state bits are greater than or equal 64.
String	group() Return the group name of the algorithm used by the random number generator.
boolean	isArbitrarilyJumpable() Return true if random generator can jump an arbitrarily specified distant point in the state cycle.
boolean	isDeprecated() Return true if the implementation of RandomGenerator (algorithm) has been marked for deprecation.
boolean	isHardware() Return true if random generator uses a hardware device (HRNG) to produce entropic input.
boolean	isJumpable() Return true if random generator can jump a specified distant point in the state cycle.
boolean	isLeapable() Return true if random generator is jumpable and can leap to a very distant point in the state cycle.
boolean	isSplittable() Return true if random generator can be cloned into a separate object with the same properties but positioned further in the state cycle.
boolean	isStatistical() Return true if random generator is computed using an arithmetic algorithm and is statistically deterministic.
boolean	isStochastic() Return true if random generator is computed using external or entropic sources as inputs.
boolean	isStreamable() Return true if random generator can be used to create Streams of random numbers.
String	name() Return the name of the algorithm used by the random number generator.
static <T extends RandomGenerator> RandomGeneratorFactory<T>	of(String name) Returns a RandomGeneratorFactory that can produce instances of RandomGenerator that utilize the name algorithm.
BigInteger	period() Return the period of the algorithm used by the random number generator.
int	stateBits() Returns number of bits used by the algorithm to maintain state of seed.

Inherited methods

From class java.lang.Object Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. final Class<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait(long timeoutMillis, int nanos) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait(long timeoutMillis) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait() Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

Public methods

all

Added in API level 35

public static Stream<RandomGeneratorFactory<RandomGenerator>> all ()

Returns a non-empty stream of available RandomGeneratorFactory(s). RandomGenerators that are marked as deprecated are not included in the result.

Implementation Requirements:

• Availability is determined by RandomGeneratorFactory using the service provider API to locate implementations of the RandomGenerator interface.

Returns
Stream<RandomGeneratorFactory<RandomGenerator>>	a non-empty stream of all available RandomGeneratorFactory(s).

create

Added in API level 35

public T create (byte[] seed)

Create an instance of RandomGenerator based on algorithm chosen providing a starting byte[] seed. If byte[] seed is not supported by an algorithm then the no argument form of create is used.

Parameters
seed	byte: byte array random seed value.

Returns
T	new in instance of RandomGenerator.

Throws
NullPointerException	if seed is null.

create

Added in API level 35

public T create (long seed)

Create an instance of RandomGenerator based on algorithm chosen providing a starting long seed. If long seed is not supported by an algorithm then the no argument form of create is used.

Parameters
seed	long: long random seed value.

Returns
T	new in instance of RandomGenerator.

create

Added in API level 35

public T create ()

Create an instance of RandomGenerator based on algorithm chosen.

Returns
T	new in instance of RandomGenerator.

equidistribution

Added in API level 35

public int equidistribution ()

Returns the equidistribution of the algorithm.

Returns
int	the equidistribution of the algorithm.

getDefault

Added in API level 35

public static RandomGeneratorFactory<RandomGenerator> getDefault ()

Returns a RandomGeneratorFactory meeting the minimal requirement of having an algorithm whose state bits are greater than or equal 64.

Implementation Requirements:

• Since algorithms will improve over time, there is no guarantee that this method will return the same algorithm over time.

Returns
RandomGeneratorFactory<RandomGenerator>	a RandomGeneratorFactory

group

Added in API level 35

public String group ()

Return the group name of the algorithm used by the random number generator.

Returns
String	Group name of the algorithm.

isArbitrarilyJumpable

Added in API level 35

public boolean isArbitrarilyJumpable ()

Return true if random generator can jump an arbitrarily specified distant point in the state cycle.

Returns
boolean	true if random generator is arbitrarily jumpable.

isDeprecated

Added in API level 35

public boolean isDeprecated ()

Return true if the implementation of RandomGenerator (algorithm) has been marked for deprecation.

Implementation Note:

• Random number generator algorithms evolve over time; new algorithms will be introduced and old algorithms will lose standing. If an older algorithm is deemed unsuitable for continued use, it will be marked as deprecated to indicate that it may be removed at some point in the future.

Returns
boolean	true if the implementation of RandomGenerator (algorithm) has been marked for deprecation

isHardware

Added in API level 35

public boolean isHardware ()

Return true if random generator uses a hardware device (HRNG) to produce entropic input.

Returns
boolean	true if random generator is generated by hardware.

isJumpable

Added in API level 35

public boolean isJumpable ()

Return true if random generator can jump a specified distant point in the state cycle.

Returns
boolean	true if random generator is jumpable.

isLeapable

Added in API level 35

public boolean isLeapable ()

Return true if random generator is jumpable and can leap to a very distant point in the state cycle.

Returns
boolean	true if random generator is leapable.

isSplittable

Added in API level 35

public boolean isSplittable ()

Return true if random generator can be cloned into a separate object with the same properties but positioned further in the state cycle.

Returns
boolean	true if random generator is splittable.

isStatistical

Added in API level 35

public boolean isStatistical ()

Return true if random generator is computed using an arithmetic algorithm and is statistically deterministic.

Returns
boolean	true if random generator is statistical.

isStochastic

Added in API level 35

public boolean isStochastic ()

Return true if random generator is computed using external or entropic sources as inputs.

Returns
boolean	true if random generator is stochastic.

isStreamable

Added in API level 35

public boolean isStreamable ()

Return true if random generator can be used to create Streams of random numbers.

Returns
boolean	true if random generator is streamable.

name

Added in API level 35

public String name ()

Return the name of the algorithm used by the random number generator.

Returns
String	Name of the algorithm.

of

Added in API level 35

public static RandomGeneratorFactory<T> of (String name)

Returns a RandomGeneratorFactory that can produce instances of RandomGenerator that utilize the name algorithm.

Implementation Requirements:

• Availability is determined by RandomGeneratorFactory using the service provider API to locate implementations of the RandomGenerator interface.

Parameters
name	String: Name of random number generator algorithm

Returns
RandomGeneratorFactory<T>	RandomGeneratorFactory of RandomGenerator

Throws
NullPointerException	if name is null
IllegalArgumentException	if the named algorithm is not found

period

Added in API level 35

public BigInteger period ()

Return the period of the algorithm used by the random number generator. Returns BigInteger.ZERO if period is not determinable.

Returns
BigInteger	BigInteger period.

stateBits

Added in API level 35

public int stateBits ()

Returns number of bits used by the algorithm to maintain state of seed.

Returns
int	number of bits used by the algorithm to maintain state of seed.