ProviderBuilder.java
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.commons.rng.simple.internal;
import java.lang.reflect.Array;
import java.lang.reflect.Constructor;
import java.lang.reflect.InvocationTargetException;
import org.apache.commons.rng.UniformRandomProvider;
import org.apache.commons.rng.RestorableUniformRandomProvider;
import org.apache.commons.rng.core.source32.JDKRandom;
import org.apache.commons.rng.core.source32.Well512a;
import org.apache.commons.rng.core.source32.Well1024a;
import org.apache.commons.rng.core.source32.Well19937a;
import org.apache.commons.rng.core.source32.Well19937c;
import org.apache.commons.rng.core.source32.Well44497a;
import org.apache.commons.rng.core.source32.Well44497b;
import org.apache.commons.rng.core.source32.ISAACRandom;
import org.apache.commons.rng.core.source32.IntProvider;
import org.apache.commons.rng.core.source32.MersenneTwister;
import org.apache.commons.rng.core.source32.MiddleSquareWeylSequence;
import org.apache.commons.rng.core.source32.MultiplyWithCarry256;
import org.apache.commons.rng.core.source32.KISSRandom;
import org.apache.commons.rng.core.source32.XoRoShiRo64Star;
import org.apache.commons.rng.core.source32.XoRoShiRo64StarStar;
import org.apache.commons.rng.core.source32.XoShiRo128Plus;
import org.apache.commons.rng.core.source32.XoShiRo128PlusPlus;
import org.apache.commons.rng.core.source32.XoShiRo128StarStar;
import org.apache.commons.rng.core.source32.PcgXshRr32;
import org.apache.commons.rng.core.source32.PcgXshRs32;
import org.apache.commons.rng.core.source32.PcgMcgXshRr32;
import org.apache.commons.rng.core.source32.PcgMcgXshRs32;
import org.apache.commons.rng.core.source32.DotyHumphreySmallFastCounting32;
import org.apache.commons.rng.core.source32.JenkinsSmallFast32;
import org.apache.commons.rng.core.source32.L32X64Mix;
import org.apache.commons.rng.core.source64.SplitMix64;
import org.apache.commons.rng.core.source64.XorShift1024Star;
import org.apache.commons.rng.core.source64.XorShift1024StarPhi;
import org.apache.commons.rng.core.source64.TwoCmres;
import org.apache.commons.rng.core.source64.XoRoShiRo1024PlusPlus;
import org.apache.commons.rng.core.source64.XoRoShiRo1024Star;
import org.apache.commons.rng.core.source64.XoRoShiRo1024StarStar;
import org.apache.commons.rng.core.source64.MersenneTwister64;
import org.apache.commons.rng.core.source64.XoRoShiRo128Plus;
import org.apache.commons.rng.core.source64.XoRoShiRo128PlusPlus;
import org.apache.commons.rng.core.source64.XoRoShiRo128StarStar;
import org.apache.commons.rng.core.source64.XoShiRo256Plus;
import org.apache.commons.rng.core.source64.XoShiRo256PlusPlus;
import org.apache.commons.rng.core.source64.XoShiRo256StarStar;
import org.apache.commons.rng.core.source64.XoShiRo512Plus;
import org.apache.commons.rng.core.source64.XoShiRo512PlusPlus;
import org.apache.commons.rng.core.source64.XoShiRo512StarStar;
import org.apache.commons.rng.core.source64.PcgRxsMXs64;
import org.apache.commons.rng.core.source64.DotyHumphreySmallFastCounting64;
import org.apache.commons.rng.core.source64.JenkinsSmallFast64;
import org.apache.commons.rng.core.source64.L64X1024Mix;
import org.apache.commons.rng.core.source64.L64X128Mix;
import org.apache.commons.rng.core.source64.L64X128StarStar;
import org.apache.commons.rng.core.source64.L64X256Mix;
import org.apache.commons.rng.core.source64.L128X1024Mix;
import org.apache.commons.rng.core.source64.L128X128Mix;
import org.apache.commons.rng.core.source64.L128X256Mix;
/**
* RNG builder.
* <p>
* It uses reflection to find the factory method of the RNG implementation,
* and performs seed type conversions.
* </p>
*/
public final class ProviderBuilder {
/** Error message. */
private static final String INTERNAL_ERROR_MSG = "Internal error: Please file a bug report";
/**
* Class only contains static method.
*/
private ProviderBuilder() {}
/**
* Creates a RNG instance.
*
* @param source RNG specification.
* @return a new RNG instance.
* @throws IllegalArgumentException if argument data to initialize the
* generator implemented by the given {@code source} is missing.
* @since 1.3
*/
public static RestorableUniformRandomProvider create(RandomSourceInternal source) {
// Delegate to the random source allowing generator specific implementations.
return source.create();
}
/**
* Creates a RNG instance.
*
* @param source RNG specification.
* @param seed Seed value. It can be {@code null} (in which case a
* random value will be used).
* @param args Additional arguments to the implementation's constructor.
* @return a new RNG instance.
* @throws UnsupportedOperationException if the seed type is invalid.
* @throws IllegalArgumentException if argument data to initialize the
* generator implemented by the given {@code source} is invalid.
*/
public static RestorableUniformRandomProvider create(RandomSourceInternal source,
Object seed,
Object[] args) {
// Delegate to the random source allowing generator specific implementations.
// This method checks arguments for null and calls the appropriate internal method.
if (args != null) {
return source.create(seed, args);
}
return seed == null ?
source.create() :
source.create(seed);
}
/**
* Identifiers of the generators.
*/
public enum RandomSourceInternal {
/** Source of randomness is {@link JDKRandom}. */
JDK(JDKRandom.class,
1,
NativeSeedType.LONG),
/** Source of randomness is {@link Well512a}. */
WELL_512_A(Well512a.class,
16, 0, 16,
NativeSeedType.INT_ARRAY),
/** Source of randomness is {@link Well1024a}. */
WELL_1024_A(Well1024a.class,
32, 0, 32,
NativeSeedType.INT_ARRAY),
/** Source of randomness is {@link Well19937a}. */
WELL_19937_A(Well19937a.class,
624, 0, 623,
NativeSeedType.INT_ARRAY),
/** Source of randomness is {@link Well19937c}. */
WELL_19937_C(Well19937c.class,
624, 0, 623,
NativeSeedType.INT_ARRAY),
/** Source of randomness is {@link Well44497a}. */
WELL_44497_A(Well44497a.class,
1391, 0, 1390,
NativeSeedType.INT_ARRAY),
/** Source of randomness is {@link Well44497b}. */
WELL_44497_B(Well44497b.class,
1391, 0, 1390,
NativeSeedType.INT_ARRAY),
/** Source of randomness is {@link MersenneTwister}. */
MT(MersenneTwister.class,
624,
NativeSeedType.INT_ARRAY),
/** Source of randomness is {@link ISAACRandom}. */
ISAAC(ISAACRandom.class,
256,
NativeSeedType.INT_ARRAY),
/** Source of randomness is {@link SplitMix64}. */
SPLIT_MIX_64(SplitMix64.class,
1,
NativeSeedType.LONG),
/** Source of randomness is {@link XorShift1024Star}. */
XOR_SHIFT_1024_S(XorShift1024Star.class,
16, 0, 16,
NativeSeedType.LONG_ARRAY),
/** Source of randomness is {@link TwoCmres}. */
TWO_CMRES(TwoCmres.class,
1,
NativeSeedType.INT),
/**
* Source of randomness is {@link TwoCmres} with explicit selection
* of the two subcycle generators.
*/
TWO_CMRES_SELECT(TwoCmres.class,
1,
NativeSeedType.INT,
Integer.TYPE,
Integer.TYPE),
/** Source of randomness is {@link MersenneTwister64}. */
MT_64(MersenneTwister64.class,
312,
NativeSeedType.LONG_ARRAY),
/** Source of randomness is {@link MultiplyWithCarry256}. */
MWC_256(MultiplyWithCarry256.class,
257, 0, 257,
NativeSeedType.INT_ARRAY),
/** Source of randomness is {@link KISSRandom}. */
KISS(KISSRandom.class,
// If zero in initial 3 positions the output is a simple LCG
4, 0, 3,
NativeSeedType.INT_ARRAY),
/** Source of randomness is {@link XorShift1024StarPhi}. */
XOR_SHIFT_1024_S_PHI(XorShift1024StarPhi.class,
16, 0, 16,
NativeSeedType.LONG_ARRAY),
/** Source of randomness is {@link XoRoShiRo64Star}. */
XO_RO_SHI_RO_64_S(XoRoShiRo64Star.class,
2, 0, 2,
NativeSeedType.INT_ARRAY),
/** Source of randomness is {@link XoRoShiRo64StarStar}. */
XO_RO_SHI_RO_64_SS(XoRoShiRo64StarStar.class,
2, 0, 2,
NativeSeedType.INT_ARRAY),
/** Source of randomness is {@link XoShiRo128Plus}. */
XO_SHI_RO_128_PLUS(XoShiRo128Plus.class,
4, 0, 4,
NativeSeedType.INT_ARRAY),
/** Source of randomness is {@link XoShiRo128StarStar}. */
XO_SHI_RO_128_SS(XoShiRo128StarStar.class,
4, 0, 4,
NativeSeedType.INT_ARRAY),
/** Source of randomness is {@link XoRoShiRo128Plus}. */
XO_RO_SHI_RO_128_PLUS(XoRoShiRo128Plus.class,
2, 0, 2,
NativeSeedType.LONG_ARRAY),
/** Source of randomness is {@link XoRoShiRo128StarStar}. */
XO_RO_SHI_RO_128_SS(XoRoShiRo128StarStar.class,
2, 0, 2,
NativeSeedType.LONG_ARRAY),
/** Source of randomness is {@link XoShiRo256Plus}. */
XO_SHI_RO_256_PLUS(XoShiRo256Plus.class,
4, 0, 4,
NativeSeedType.LONG_ARRAY),
/** Source of randomness is {@link XoShiRo256StarStar}. */
XO_SHI_RO_256_SS(XoShiRo256StarStar.class,
4, 0, 4,
NativeSeedType.LONG_ARRAY),
/** Source of randomness is {@link XoShiRo512Plus}. */
XO_SHI_RO_512_PLUS(XoShiRo512Plus.class,
8, 0, 8,
NativeSeedType.LONG_ARRAY),
/** Source of randomness is {@link XoShiRo512StarStar}. */
XO_SHI_RO_512_SS(XoShiRo512StarStar.class,
8, 0, 8,
NativeSeedType.LONG_ARRAY),
/** Source of randomness is {@link PcgXshRr32}. */
PCG_XSH_RR_32(PcgXshRr32.class,
2,
NativeSeedType.LONG_ARRAY),
/** Source of randomness is {@link PcgXshRs32}. */
PCG_XSH_RS_32(PcgXshRs32.class,
2,
NativeSeedType.LONG_ARRAY),
/** Source of randomness is {@link PcgRxsMXs64}. */
PCG_RXS_M_XS_64(PcgRxsMXs64.class,
2,
NativeSeedType.LONG_ARRAY),
/** Source of randomness is {@link PcgMcgXshRr32}. */
PCG_MCG_XSH_RR_32(PcgMcgXshRr32.class,
1,
NativeSeedType.LONG),
/** Source of randomness is {@link PcgMcgXshRs32}. */
PCG_MCG_XSH_RS_32(PcgMcgXshRs32.class,
1,
NativeSeedType.LONG),
/** Source of randomness is {@link MiddleSquareWeylSequence}. */
MSWS(MiddleSquareWeylSequence.class,
// Many partially zero seeds can create low quality initial output.
// The Weyl increment cascades bits into the random state so ideally it
// has a high number of bit transitions. Minimally ensure it is non-zero.
3, 2, 3,
NativeSeedType.LONG_ARRAY) {
@Override
protected Object createSeed() {
return createMswsSeed(SeedFactory.createLong());
}
@Override
protected Object convertSeed(Object seed) {
// Allow seeding with primitives to generate a good seed
if (seed instanceof Integer) {
return createMswsSeed((Integer) seed);
} else if (seed instanceof Long) {
return createMswsSeed((Long) seed);
}
// Other types (e.g. the native long[]) are handled by the default conversion
return super.convertSeed(seed);
}
@Override
protected byte[] createByteArraySeed(UniformRandomProvider source) {
// The seed requires approximately 4-6 calls to nextInt().
// Wrap the input and switch to a default if the input is faulty.
final UniformRandomProvider wrapped = new IntProvider() {
/** The number of remaining calls to the source generator. */
private int calls = 100;
/** Default generator, initialised when required. */
private UniformRandomProvider defaultGen;
@Override
public int next() {
if (calls == 0) {
// The input source is broken.
// Seed a default
if (defaultGen == null) {
defaultGen = new SplitMix64(source.nextLong());
}
return defaultGen.nextInt();
}
calls--;
return source.nextInt();
}
@Override
public long nextLong() {
// No specific requirements so always use the source
return source.nextLong();
}
};
return NativeSeedType.convertSeedToBytes(createMswsSeed(wrapped));
}
/**
* Creates the full length seed array from the input seed.
*
* @param seed the seed
* @return the seed array
*/
private long[] createMswsSeed(long seed) {
return createMswsSeed(new SplitMix64(seed));
}
/**
* Creates the full length seed array from the input seed using the method
* recommended for the generator. This is a high quality Weyl increment composed
* of a hex character permutation.
*
* @param source Source of randomness.
* @return the seed array
*/
private long[] createMswsSeed(UniformRandomProvider source) {
final long increment = SeedUtils.createLongHexPermutation(source);
// The initial state should not be low complexity but the Weyl
// state can be any number.
final long state = increment;
final long weylState = source.nextLong();
return new long[] {state, weylState, increment};
}
},
/** Source of randomness is {@link DotyHumphreySmallFastCounting32}. */
SFC_32(DotyHumphreySmallFastCounting32.class,
3,
NativeSeedType.INT_ARRAY),
/** Source of randomness is {@link DotyHumphreySmallFastCounting64}. */
SFC_64(DotyHumphreySmallFastCounting64.class,
3,
NativeSeedType.LONG_ARRAY),
/** Source of randomness is {@link JenkinsSmallFast32}. */
JSF_32(JenkinsSmallFast32.class,
1,
NativeSeedType.INT),
/** Source of randomness is {@link JenkinsSmallFast64}. */
JSF_64(JenkinsSmallFast64.class,
1,
NativeSeedType.LONG),
/** Source of randomness is {@link XoShiRo128PlusPlus}. */
XO_SHI_RO_128_PP(XoShiRo128PlusPlus.class,
4, 0, 4,
NativeSeedType.INT_ARRAY),
/** Source of randomness is {@link XoRoShiRo128PlusPlus}. */
XO_RO_SHI_RO_128_PP(XoRoShiRo128PlusPlus.class,
2, 0, 2,
NativeSeedType.LONG_ARRAY),
/** Source of randomness is {@link XoShiRo256PlusPlus}. */
XO_SHI_RO_256_PP(XoShiRo256PlusPlus.class,
4, 0, 4,
NativeSeedType.LONG_ARRAY),
/** Source of randomness is {@link XoShiRo512PlusPlus}. */
XO_SHI_RO_512_PP(XoShiRo512PlusPlus.class,
8, 0, 8,
NativeSeedType.LONG_ARRAY),
/** Source of randomness is {@link XoRoShiRo1024PlusPlus}. */
XO_RO_SHI_RO_1024_PP(XoRoShiRo1024PlusPlus.class,
16, 0, 16,
NativeSeedType.LONG_ARRAY),
/** Source of randomness is {@link XoRoShiRo1024Star}. */
XO_RO_SHI_RO_1024_S(XoRoShiRo1024Star.class,
16, 0, 16,
NativeSeedType.LONG_ARRAY),
/** Source of randomness is {@link XoRoShiRo1024StarStar}. */
XO_RO_SHI_RO_1024_SS(XoRoShiRo1024StarStar.class,
16, 0, 16,
NativeSeedType.LONG_ARRAY),
/** Source of randomness is {@link PcgXshRr32}. */
PCG_XSH_RR_32_OS(PcgXshRr32.class,
1,
NativeSeedType.LONG),
/** Source of randomness is {@link PcgXshRs32}. */
PCG_XSH_RS_32_OS(PcgXshRs32.class,
1,
NativeSeedType.LONG),
/** Source of randomness is {@link PcgRxsMXs64}. */
PCG_RXS_M_XS_64_OS(PcgRxsMXs64.class,
1,
NativeSeedType.LONG),
/** Source of randomness is {@link L64X128StarStar}. */
L64_X128_SS(L64X128StarStar.class,
4, 2, 4,
NativeSeedType.LONG_ARRAY),
/** Source of randomness is {@link L64X128Mix}. */
L64_X128_MIX(L64X128Mix.class,
4, 2, 4,
NativeSeedType.LONG_ARRAY),
/** Source of randomness is {@link L64X256Mix}. */
L64_X256_MIX(L64X256Mix.class,
6, 2, 6,
NativeSeedType.LONG_ARRAY),
/** Source of randomness is {@link L64X1024Mix}. */
L64_X1024_MIX(L64X1024Mix.class,
18, 2, 18,
NativeSeedType.LONG_ARRAY),
/** Source of randomness is {@link L128X128Mix}. */
L128_X128_MIX(L128X128Mix.class,
6, 4, 6,
NativeSeedType.LONG_ARRAY),
/** Source of randomness is {@link L128X256Mix}. */
L128_X256_MIX(L128X256Mix.class,
8, 4, 8,
NativeSeedType.LONG_ARRAY),
/** Source of randomness is {@link L128X1024Mix}. */
L128_X1024_MIX(L128X1024Mix.class,
20, 4, 20,
NativeSeedType.LONG_ARRAY),
/** Source of randomness is {@link L32X64Mix}. */
L32_X64_MIX(L32X64Mix.class,
4, 2, 4,
NativeSeedType.INT_ARRAY);
/** Source type. */
private final Class<? extends UniformRandomProvider> rng;
/** Native seed size. Used for array seeds. */
private final int nativeSeedSize;
/** Start of the not all-zero sub-range for array seeds (inclusive). */
private final int notAllZeroFrom;
/** End of the not all-zero sub-range for array seeds (exclusive). */
private final int notAllZeroTo;
/** Define the parameter types of the data needed to build the generator. */
private final Class<?>[] args;
/** Native seed type. Used to create a seed or convert input seeds. */
private final NativeSeedType nativeSeedType;
/**
* The constructor.
* This is discovered using the constructor parameter types and stored for re-use.
*/
private Constructor<?> rngConstructor;
/**
* Create a new instance.
*
* <p>Used when the seed array has no requirement for a not all-zero sub-range.
*
* @param rng Source type.
* @param nativeSeedSize Native seed size (array types only).
* @param nativeSeedType Native seed type.
* @param args Additional data needed to create a generator instance.
*/
RandomSourceInternal(Class<? extends UniformRandomProvider> rng,
int nativeSeedSize,
NativeSeedType nativeSeedType,
Class<?>... args) {
this(rng, nativeSeedSize, 0, 0, nativeSeedType, args);
}
/**
* Create a new instance.
*
* <p>Note: The sub-range of an array seed that is not all-zero can be specified.
* If the native seed array is used to represent a number of bits
* that is not an exact multiple of the number of bytes in the seed, then a
* safe approach is to specify the sub-range using a smaller size than the
* full length seed. For example a {@link Well19937a} generator uses 19937
* bits and has a seed bit length of 19968. A safe range is [0, 19937 / 32).
*
* @param rng Source type.
* @param nativeSeedSize Native seed size (array types only).
* @param notAllZeroFrom The start of the not all-zero sub-range (inclusive).
* @param notAllZeroTo The end of the not all-zero sub-range (exclusive).
* @param nativeSeedType Native seed type.
* @param args Additional data needed to create a generator instance.
*/
RandomSourceInternal(Class<? extends UniformRandomProvider> rng,
int nativeSeedSize,
int notAllZeroFrom,
int notAllZeroTo,
NativeSeedType nativeSeedType,
Class<?>... args) {
this.rng = rng;
this.nativeSeedSize = nativeSeedSize;
this.notAllZeroFrom = notAllZeroFrom;
this.notAllZeroTo = notAllZeroTo;
this.nativeSeedType = nativeSeedType;
// Build the complete list of class types for the constructor
this.args = (Class<?>[]) Array.newInstance(args.getClass().getComponentType(), 1 + args.length);
this.args[0] = nativeSeedType.getType();
System.arraycopy(args, 0, this.args, 1, args.length);
}
/**
* Gets the implementing class of the random source.
*
* @return the random source class.
*/
public Class<?> getRng() {
return rng;
}
/**
* Gets the class of the native seed.
*
* @return the seed class.
*/
Class<?> getSeed() {
return args[0];
}
/**
* Gets the parameter types of the data needed to build the generator.
*
* @return the data needed to build the generator.
*/
Class<?>[] getArgs() {
return args;
}
/**
* Checks whether the type of given {@code seed} is the native type
* of the implementation.
*
* @param <SEED> Seed type.
*
* @param seed Seed value.
* @return {@code true} if the seed can be passed to the builder
* for this RNG type.
*/
public <SEED> boolean isNativeSeed(SEED seed) {
return seed != null && getSeed().equals(seed.getClass());
}
/**
* Creates a RNG instance.
*
* <p>This method can be over-ridden to allow fast construction of a generator
* with low seeding cost that has no additional constructor arguments.</p>
*
* @return a new RNG instance.
*/
RestorableUniformRandomProvider create() {
// Create a seed.
final Object nativeSeed = createSeed();
// Instantiate.
return create(getConstructor(), new Object[] {nativeSeed});
}
/**
* Creates a RNG instance. It is assumed the seed is not {@code null}.
*
* <p>This method can be over-ridden to allow fast construction of a generator
* with low seed conversion cost that has no additional constructor arguments.</p>
*
* @param seed Seed value. It must not be {@code null}.
* @return a new RNG instance.
* @throws UnsupportedOperationException if the seed type is invalid.
*/
RestorableUniformRandomProvider create(Object seed) {
// Convert seed to native type.
final Object nativeSeed = convertSeed(seed);
// Instantiate.
return create(getConstructor(), new Object[] {nativeSeed});
}
/**
* Creates a RNG instance. This constructs a RNG using reflection and will error
* if the constructor arguments do not match those required by the RNG's constructor.
*
* @param seed Seed value. It can be {@code null} (in which case a suitable
* seed will be generated).
* @param constructorArgs Additional arguments to the implementation's constructor.
* It must not be {@code null}.
* @return a new RNG instance.
* @throws UnsupportedOperationException if the seed type is invalid.
*/
RestorableUniformRandomProvider create(Object seed,
Object[] constructorArgs) {
final Object nativeSeed = createNativeSeed(seed);
// Build a single array with all the arguments to be passed
// (in the right order) to the constructor.
Object[] all = new Object[constructorArgs.length + 1];
all[0] = nativeSeed;
System.arraycopy(constructorArgs, 0, all, 1, constructorArgs.length);
// Instantiate.
return create(getConstructor(), all);
}
/**
* Creates a native seed.
*
* <p>The default implementation creates a seed of the native type and, for array seeds,
* ensures not all bits are zero.</p>
*
* <p>This method should be over-ridden to satisfy seed requirements for the generator.</p>
*
* @return the native seed
* @since 1.3
*/
protected Object createSeed() {
// Ensure the seed is not all-zero in the sub-range
return nativeSeedType.createSeed(nativeSeedSize, notAllZeroFrom, notAllZeroTo);
}
/**
* Creates a {@code byte[]} seed using the provided source of randomness.
*
* <p>The default implementation creates a full-length seed and ensures not all bits
* are zero.</p>
*
* <p>This method should be over-ridden to satisfy seed requirements for the generator.</p>
*
* @param source Source of randomness.
* @return the byte[] seed
* @since 1.3
*/
protected byte[] createByteArraySeed(UniformRandomProvider source) {
// Ensure the seed is not all-zero in the sub-range.
// Note: Convert the native seed array size/positions to byte size/positions.
final int bytes = nativeSeedType.getBytes();
return SeedFactory.createByteArray(source,
bytes * nativeSeedSize,
bytes * notAllZeroFrom,
bytes * notAllZeroTo);
}
/**
* Converts a seed from any of the supported seed types to a native seed.
*
* <p>The default implementation delegates to the native seed type conversion.</p>
*
* <p>This method should be over-ridden to satisfy seed requirements for the generator.</p>
*
* @param seed Input seed (must not be null).
* @return the native seed
* @throws UnsupportedOperationException if the {@code seed} type is invalid.
* @since 1.3
*/
protected Object convertSeed(Object seed) {
return nativeSeedType.convertSeed(seed, nativeSeedSize);
}
/**
* Creates a native seed from any of the supported seed types.
*
* @param seed Input seed (may be null).
* @return the native seed.
* @throws UnsupportedOperationException if the {@code seed} type cannot be converted.
*/
private Object createNativeSeed(Object seed) {
return seed == null ?
createSeed() :
convertSeed(seed);
}
/**
* Creates a seed suitable for the implementing class represented by this random source.
*
* <p>It will satisfy the seed size and any other seed requirements for the
* implementing class. The seed is converted from the native type to bytes.</p>
*
* @return the seed bytes
* @since 1.3
*/
public final byte[] createSeedBytes() {
// Custom implementations can override createSeed
final Object seed = createSeed();
return NativeSeedType.convertSeedToBytes(seed);
}
/**
* Creates a seed suitable for the implementing class represented by this random source
* using the supplied source of randomness.
*
* <p>It will satisfy the seed size and any other seed requirements for the
* implementing class. The seed is converted from the native type to bytes.</p>
*
* @param source Source of randomness.
* @return the seed bytes
* @since 1.3
*/
public final byte[] createSeedBytes(UniformRandomProvider source) {
// Custom implementations can override createByteArraySeed
return createByteArraySeed(source);
}
/**
* Gets the constructor.
*
* @return the RNG constructor.
*/
private Constructor<?> getConstructor() {
// The constructor never changes so it is stored for re-use.
Constructor<?> constructor = rngConstructor;
if (constructor == null) {
// If null this is either the first attempt to find it or
// look-up previously failed and this method will throw
// upon each invocation.
constructor = createConstructor();
rngConstructor = constructor;
}
return constructor;
}
/**
* Creates a constructor.
*
* @return a RNG constructor.
*/
private Constructor<?> createConstructor() {
try {
return getRng().getConstructor(getArgs());
} catch (NoSuchMethodException e) {
// Info in "RandomSourceInternal" is inconsistent with the
// constructor of the implementation.
throw new IllegalStateException(INTERNAL_ERROR_MSG, e);
}
}
/**
* Creates a RNG.
*
* @param rng RNG specification.
* @param args Arguments to the implementation's constructor.
* @return a new RNG instance.
*/
private static RestorableUniformRandomProvider create(Constructor<?> rng,
Object[] args) {
try {
return (RestorableUniformRandomProvider) rng.newInstance(args);
} catch (InvocationTargetException | InstantiationException | IllegalAccessException e) {
throw new IllegalStateException(INTERNAL_ERROR_MSG, e);
}
}
}
}