FACTORY_MAP = createFactoryMap();
/**
* Returns the factory map, lazily constructing it on first use.
* Although {@link ThreadLocalRandom} can only be accessed via
* {@link ThreadLocalRandom#current()}, a map entry is added nevertheless
* to record its properties that are otherwise not documented
* anywhere else.
*
Currently, no algorithm is deprecated.
*
* @return Map of RandomGeneratorProperties.
*/
private static Map createFactoryMap() {
return Map.ofEntries(
entry(SecureRandom.class, "SecureRandom", "Legacy",
0, 0, 0, Integer.MAX_VALUE,
INSTANTIABLE | BYTE_ARRAY_SEED | STOCHASTIC | deprecationBit(SecureRandom.class)),
entry(Random.class, "Random", "Legacy",
48, 0, 0, 0,
INSTANTIABLE | LONG_SEED | deprecationBit(Random.class)),
entry(SplittableRandom.class, "SplittableRandom", "Legacy",
64, 0, 0, 1,
INSTANTIABLE | LONG_SEED | deprecationBit(SplittableRandom.class)),
entry(L32X64MixRandom.class, "L32X64MixRandom", "LXM",
64, 1, 32, 1,
ALL_CONSTRUCTORS),
entry(L64X128MixRandom.class, "L64X128MixRandom", "LXM",
128, 1, 64, 2,
ALL_CONSTRUCTORS),
entry(L64X128StarStarRandom.class, "L64X128StarStarRandom", "LXM",
128, 1, 64, 2,
ALL_CONSTRUCTORS),
entry(L64X256MixRandom.class, "L64X256MixRandom", "LXM",
256, 1, 64, 4,
ALL_CONSTRUCTORS),
entry(L64X1024MixRandom.class, "L64X1024MixRandom", "LXM",
1024, 1, 64, 16,
ALL_CONSTRUCTORS),
entry(L128X128MixRandom.class, "L128X128MixRandom", "LXM",
128, 1, 128, 1,
ALL_CONSTRUCTORS),
entry(L128X256MixRandom.class, "L128X256MixRandom", "LXM",
256, 1, 128, 1,
ALL_CONSTRUCTORS),
entry(L128X1024MixRandom.class, "L128X1024MixRandom", "LXM",
1024, 1, 128, 1,
ALL_CONSTRUCTORS),
entry(Xoroshiro128PlusPlus.class, "Xoroshiro128PlusPlus", "Xoroshiro",
128, 1, 0, 1,
ALL_CONSTRUCTORS),
entry(Xoshiro256PlusPlus.class, "Xoshiro256PlusPlus", "Xoshiro",
256, 1, 0, 3,
ALL_CONSTRUCTORS),
entry(ThreadLocalRandom.class, "ThreadLocalRandom", "Legacy",
64, 0, 0, 1,
deprecationBit(ThreadLocalRandom.class))
);
}
private static Map.Entry entry(
Class rgClass, String name, String group,
int i, int j, int k, int equidistribution,
int flags) {
return Map.entry(name,
new RandomGeneratorProperties(rgClass, name, group,
i, j, k, equidistribution,
flags));
}
private static int deprecationBit(Class rgClass) {
return rgClass.isAnnotationPresent(Deprecated.class) ? DEPRECATED : 0;
}
private RandomGenerator create() {
return switch (name) {
case "Random" -> new Random();
case "SecureRandom" -> new SecureRandom();
case "SplittableRandom" -> new SplittableRandom();
case "L32X64MixRandom" -> new L32X64MixRandom();
case "L64X128MixRandom" -> new L64X128MixRandom();
case "L64X128StarStarRandom" -> new L64X128StarStarRandom();
case "L64X256MixRandom" -> new L64X256MixRandom();
case "L64X1024MixRandom" -> new L64X1024MixRandom();
case "L128X128MixRandom" -> new L128X128MixRandom();
case "L128X256MixRandom" -> new L128X256MixRandom();
case "L128X1024MixRandom" -> new L128X1024MixRandom();
case "Xoroshiro128PlusPlus" -> new Xoroshiro128PlusPlus();
case "Xoshiro256PlusPlus" -> new Xoshiro256PlusPlus();
default -> throw new InternalError("should not happen");
};
}
private RandomGenerator create(long seed) {
if (isInstantiable() && (flags & LONG_SEED) == 0) {
throw new UnsupportedOperationException("Random algorithm "
+ name + " does not support a long seed");
}
return switch (name) {
case "Random" -> new Random(seed);
case "SplittableRandom" -> new SplittableRandom(seed);
case "L32X64MixRandom" -> new L32X64MixRandom(seed);
case "L64X128MixRandom" -> new L64X128MixRandom(seed);
case "L64X128StarStarRandom" -> new L64X128StarStarRandom(seed);
case "L64X256MixRandom" -> new L64X256MixRandom(seed);
case "L64X1024MixRandom" -> new L64X1024MixRandom(seed);
case "L128X128MixRandom" -> new L128X128MixRandom(seed);
case "L128X256MixRandom" -> new L128X256MixRandom(seed);
case "L128X1024MixRandom" -> new L128X1024MixRandom(seed);
case "Xoroshiro128PlusPlus" -> new Xoroshiro128PlusPlus(seed);
case "Xoshiro256PlusPlus" -> new Xoshiro256PlusPlus(seed);
default -> throw new InternalError("should not happen");
};
}
private RandomGenerator create(byte[] seed) {
if (isInstantiable() && (flags & BYTE_ARRAY_SEED) == 0) {
throw new UnsupportedOperationException("Random algorithm "
+ name + " does not support a byte[] seed");
}
return switch (name) {
case "SecureRandom" -> new SecureRandom(seed);
case "L32X64MixRandom" -> new L32X64MixRandom(seed);
case "L64X128MixRandom" -> new L64X128MixRandom(seed);
case "L64X128StarStarRandom" -> new L64X128StarStarRandom(seed);
case "L64X256MixRandom" -> new L64X256MixRandom(seed);
case "L64X1024MixRandom" -> new L64X1024MixRandom(seed);
case "L128X128MixRandom" -> new L128X128MixRandom(seed);
case "L128X256MixRandom" -> new L128X256MixRandom(seed);
case "L128X1024MixRandom" -> new L128X1024MixRandom(seed);
case "Xoroshiro128PlusPlus" -> new Xoroshiro128PlusPlus(seed);
case "Xoshiro256PlusPlus" -> new Xoshiro256PlusPlus(seed);
default -> throw new InternalError("should not happen");
};
}
private boolean isStochastic() {
return (flags & STOCHASTIC) != 0;
}
private boolean isHardware() {
return (flags & HARDWARE) != 0;
}
private boolean isInstantiable() {
return (flags & INSTANTIABLE) != 0;
}
private boolean isDeprecated() {
return (flags & DEPRECATED) != 0;
}
private BigInteger period() {
/*
* 0 if i = j = k = 0
* (2^i - j) 2^k otherwise
*/
return i == 0 && j == 0 && k == 0
? BigInteger.ZERO
: BigInteger.ONE.shiftLeft(i).subtract(BigInteger.valueOf(j)).shiftLeft(k);
}
private int stateBits() {
return i == 0 && k == 0 ? Integer.MAX_VALUE : i + k;
}
}
/**
* Random generator properties.
*/
private final RandomGeneratorProperties properties;
/**
* Private constructor.
*
* @param properties Random generator properties.
*/
private RandomGeneratorFactory(RandomGeneratorProperties properties) {
this.properties = properties;
}
/**
* Returns the factory map, lazily constructing the map on first call.
*
* @return Map of random generator classes.
*/
private static Map getFactoryMap() {
return RandomGeneratorProperties.FACTORY_MAP;
}
/**
* Return true if the random generator class is a subclass of the category.
*
* @param category Interface category, sub-interface of {@link RandomGenerator}.
*
* @return true if the random generator class is a subclass of the category.
*/
private boolean isSubclass(Class category) {
return isSubclass(category, properties.rgClass());
}
/**
* Return true if rgClass is a subclass of the category.
*
* @param category Interface category, sub-interface of {@link RandomGenerator}.
* @param rgClass Class that is being filtered.
*
* @return true if rgClass is a subclass of the category.
*/
private static boolean isSubclass(Class category,
Class rgClass) {
return rgClass != null && category.isAssignableFrom(rgClass);
}
/**
* Returns a RandomGeneratorProperties instance matching name and category.
*
* @param name Name of RandomGenerator
* @param category Interface category, sub-interface of {@link RandomGenerator}.
* @return A RandomGeneratorProperties instance matching name and category.
* @throws IllegalArgumentException if the resulting type is not a subclass of category.
*/
private static RandomGeneratorProperties findClass(String name,
Class category) throws IllegalArgumentException {
RandomGeneratorProperties properties = name != null
? getFactoryMap().get(name)
: null;
if (properties == null || !properties.isInstantiable()) {
throw new IllegalArgumentException("No implementation of the random number generator algorithm \"" +
name +
"\" is available");
}
if (!isSubclass(category, properties.rgClass())) {
throw new IllegalArgumentException("The random number generator algorithm \"" +
name +
"\" is not implemented with the interface \"" +
category.getSimpleName() +
"\"");
}
return properties;
}
/**
* Returns a {@link RandomGenerator} that utilizes the {@code name}
* algorithm.
*
* @param name Name of random number algorithm to use
* @param category Sub-interface of {@link RandomGenerator} to type check
* @param Sub-interface of {@link RandomGenerator} to produce
*
* @return An instance of {@link RandomGenerator}
*
* @throws IllegalArgumentException when either the name or category is null
*/
static T of(String name, Class category)
throws IllegalArgumentException {
@SuppressWarnings("unchecked")
T instance = (T) findClass(name, category).create();
return instance;
}
/**
* Returns a {@link RandomGeneratorFactory} that will produce instances
* of {@link RandomGenerator} that utilizes the named algorithm.
*
* @param name Name of random number algorithm to use
* @param category Sub-interface of {@link RandomGenerator} to type check
* @param Sub-interface of {@link RandomGenerator} to produce
*
* @return Factory of {@link RandomGenerator}
*
* @throws IllegalArgumentException when either the name or category is null
*/
static RandomGeneratorFactory factoryOf(String name, Class category)
throws IllegalArgumentException {
return new RandomGeneratorFactory<>(findClass(name, category));
}
/**
* Returns a {@link RandomGeneratorFactory} that can produce instances of
* {@link RandomGenerator} that utilize the {@code name}
* algorithm.
*
* @param name Name of random number generator
* algorithm
* @param Sub-interface of {@link RandomGenerator} to produce
*
* @return {@link RandomGeneratorFactory} of {@link RandomGenerator}
*
* @throws NullPointerException if name is null
* @throws IllegalArgumentException if the named algorithm is not found
*/
public static RandomGeneratorFactory of(String name) {
Objects.requireNonNull(name);
@SuppressWarnings("unchecked")
RandomGeneratorFactory factory =
(RandomGeneratorFactory) factoryOf(name, RandomGenerator.class);
return factory;
}
/**
* Returns a {@link RandomGeneratorFactory} meeting the minimal requirement
* of having an algorithm whose state bits are greater than or equal 64.
*
* @implSpec Since algorithms will improve over time, there is no
* guarantee that this method will return the same algorithm over time.
*
* @return a {@link RandomGeneratorFactory}
*/
public static RandomGeneratorFactory getDefault() {
return factoryOf(DEFAULT_ALGORITHM, RandomGenerator.class);
}
/**
* Returns a non-empty stream of available {@link RandomGeneratorFactory RandomGeneratorFactory(s)}.
*
* RandomGenerators that are marked as deprecated are not included in the result.
*
* @return a non-empty stream of all available {@link RandomGeneratorFactory RandomGeneratorFactory(s)}.
*/
public static Stream> all() {
return getFactoryMap().values()
.stream()
.filter(p -> p.isInstantiable() && !p.isDeprecated())
.map(RandomGeneratorFactory::new);
}
/**
* Return the name of the algorithm
* used by the random number generator.
*
* @return Name of the algorithm.
*/
public String name() {
return properties.name();
}
/**
* Return the group name of the algorithm
* used by the random number generator.
*
* @return Group name of the algorithm.
*/
public String group() {
return properties.group();
}
/**
* Returns number of bits used by the algorithm
* to maintain state of seed.
*
* @return number of bits used by the algorithm
* to maintain state of seed.
*/
public int stateBits() {
return properties.stateBits();
}
/**
* Returns the equidistribution of the algorithm.
*
* @return the equidistribution of the algorithm.
*/
public int equidistribution() {
return properties.equidistribution();
}
/**
* Return the period of the algorithm
* used by the random number generator.
* Returns BigInteger.ZERO if period is not determinable.
*
* @return BigInteger period.
*/
public BigInteger period() {
return properties.period();
}
/**
* Return true if random generator is computed using an arithmetic
* algorithm
* and is statistically deterministic.
*
* @return true if random generator is statistical.
*/
public boolean isStatistical() {
return !properties.isStochastic();
}
/**
* Return true if random generator is computed using external or entropic
* sources as inputs.
*
* @return true if random generator is stochastic.
*/
public boolean isStochastic() {
return properties.isStochastic();
}
/**
* Return true if random generator uses a hardware device (HRNG) to produce
* entropic input.
*
* @return true if random generator is generated by hardware.
*/
public boolean isHardware() {
return properties.isHardware();
}
/**
* Return true if random generator can jump an arbitrarily specified distant
* point in the state cycle.
*
* @return true if random generator is arbitrarily jumpable.
*/
public boolean isArbitrarilyJumpable() {
return isSubclass(ArbitrarilyJumpableGenerator.class);
}
/**
* Return true if random generator can jump a specified distant point in
* the state cycle.
*
* @return true if random generator is jumpable.
*/
public boolean isJumpable() {
return isSubclass(JumpableGenerator.class);
}
/**
* Return true if random generator is jumpable and can leap to a very distant
* point in the state cycle.
*
* @return true if random generator is leapable.
*/
public boolean isLeapable() {
return isSubclass(LeapableGenerator.class);
}
/**
* Return true if random generator can be cloned into a separate object with
* the same properties but positioned further in the state cycle.
*
* @return true if random generator is splittable.
*/
public boolean isSplittable() {
return isSubclass(SplittableGenerator.class);
}
/**
* Return true if random generator can be used to create
* {@link java.util.stream.Stream Streams} of random numbers.
*
* @return true if random generator is streamable.
*/
public boolean isStreamable() {
return isSubclass(StreamableGenerator.class);
}
/**
* Return true if the implementation of RandomGenerator (algorithm) has been
* marked for deprecation.
*
* @implNote 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.
*
* @return true if the implementation of RandomGenerator (algorithm) has been
* marked for deprecation
*/
public boolean isDeprecated() {
return properties.isDeprecated();
}
/**
* Create an instance of {@link RandomGenerator} based on the
* algorithm chosen.
*
* @return new instance of {@link RandomGenerator}.
*/
public T create() {
@SuppressWarnings("unchecked")
T instance = (T) properties.create();
return instance;
}
/**
* Create an instance of {@link RandomGenerator} based on the
* algorithm chosen,
* and the provided {@code seed}.
* If the {@link RandomGenerator} doesn't support instantiation through
* a {@code seed} of type {@code long} then this method throws
* an {@link UnsupportedOperationException}.
*
* @param seed long random seed value.
*
* @return new instance of {@link RandomGenerator}.
*
* @throws UnsupportedOperationException
* if a {@code seed} of type {@code long} in not supported.
*/
public T create(long seed) {
@SuppressWarnings("unchecked")
T instance = (T) properties.create(seed);
return instance;
}
/**
* Create an instance of {@link RandomGenerator} based on the
* algorithm chosen,
* and the provided {@code seed}.
* If the {@link RandomGenerator} doesn't support instantiation through
* a {@code seed} of type {@code byte[]} then this method throws
* an {@link UnsupportedOperationException}.
*
* @param seed byte array random seed value.
*
* @return new instance of {@link RandomGenerator}.
*
* @throws UnsupportedOperationException
* if a {@code seed} of type {@code byte[]} in not supported.
*
* @throws NullPointerException if seed is null.
*/
public T create(byte[] seed) {
Objects.requireNonNull(seed, "seed must not be null");
@SuppressWarnings("unchecked")
T instance = (T) properties.create(seed);
return instance;
}
}