Package io.github.pr0methean.betterrandom.prng.adapter

Class RandomWrapper<T extends Random>

java.lang.Object

java.util.Random

io.github.pr0methean.betterrandom.prng.BaseRandom

io.github.pr0methean.betterrandom.prng.adapter.RandomWrapper<T>

All Implemented Interfaces:

ByteArrayReseedableRandom, EntropyCountingRandom, RepeatableRandom, Dumpable, Serializable

Direct Known Subclasses:

EntropyBlockingRandomWrapper, ThreadLocalRandomWrapper

public class RandomWrapper<T extends Random>
extends BaseRandom

Wraps any Random as a RepeatableRandom and ByteArrayReseedableRandom. Can be used to encapsulate away a change of implementation in midstream.

Caution: This depends on the delegate's thread-safety. When used with a vanilla Random, this means that its output for the same seed will vary when accessed concurrently from multiple threads, at least on JDK 7 and 8, if the calls include e.g. BaseRandom.nextLong(), nextGaussian() or BaseRandom.nextDouble(). However, nextInt() will still be transactional.

Author:

Chris Hennick

See Also:

Serialized Form

Field Summary

Fields inherited from class io.github.pr0methean.betterrandom.prng.BaseRandom

ENTROPY_OF_DOUBLE, ENTROPY_OF_FLOAT, entropyBits, lock, randomSeeder, seed, superConstructorFinished

Constructor Summary

Constructors

Constructor	Description
RandomWrapper(T wrapped)	Creates an instance wrapping the given Random.

Method Summary

Modifier and Type	Method	Description
protected MoreObjects.ToStringHelper	addSubclassFields(MoreObjects.ToStringHelper original)	Adds the fields that were not inherited from BaseRandom to the given MoreObjects.ToStringHelper for dumping.
int	getNewSeedLength()	Returns the preferred length of a new byte-array seed.
byte[]	getSeed()	Returns the wrapped PRNG's seed, if we know it.
T	getWrapped()	Returns the PRNG this RandomWrapper is currently wrapping.
protected int	next(int bits)	Generates the next pseudorandom number.
boolean	nextBoolean()
void	nextBytes(byte[] bytes)	Generates random bytes and places them into a user-supplied byte array.
double	nextDoubleNoEntropyDebit()	Returns the next random double between 0.0 (inclusive) and 1.0 (exclusive), but does not debit entropy.
float	nextFloat()
double	nextGaussian()	Returns the next pseudorandom, Gaussian ("normally") distributed double value with mean 0.0 and standard deviation 1.0 from this random number generator's sequence.
int	nextInt()
int	nextInt(int bound)
protected long	nextLongNoEntropyDebit()	Returns the next random long, but does not debit entropy.
boolean	preferSeedWithLong()	Indicates whether Random.setSeed(long) is recommended over ByteArrayReseedableRandom.setSeed(byte[]) when the seed is already in the form of a long.
protected void	setInitiallyKnownSeed(byte[] seed)	Updates BaseRandom.seed and BaseRandom.entropyBits without reseeding the wrapped PRNG.
void	setSeed(long seed)	Sets the seed of this random number generator using a single long seed, if this implementation supports that.
protected void	setSeedInternal(byte[] seed)	Delegates to one of ByteArrayReseedableRandom.setSeed(byte[]), SecureRandom.setSeed(byte[]) or Random.setSeed(long).
void	setWrapped(T wrapped)	Replaces the wrapped PRNG with the given one on subsequent calls.
protected boolean	supportsMultipleSeedLengths()	If true, the subclass takes responsibility for checking whether the seed is non-null and has a valid length, and should throw an IllegalArgumentException in BaseRandom.setSeedInternal(byte[]) if not.
String	toString()
boolean	usesParallelStreams()
static RandomWrapper<Random>	wrapJavaUtilRandom(byte[] seed)	Creates an instance wrapping a basic Random.
static RandomWrapper<Random>	wrapJavaUtilRandom(long seed)	Creates an instance wrapping a basic Random.
static RandomWrapper<Random>	wrapJavaUtilRandom(SeedGenerator seedGenerator)	Creates an instance wrapping a basic Random.
static RandomWrapper<SecureRandom>	wrapSecureRandom(byte[] seed)	Creates an instance wrapping a basic SecureRandom with a given seed.

Methods inherited from class io.github.pr0methean.betterrandom.prng.BaseRandom

checkLength, checkValidRange, creditEntropyForNewSeed, debitEntropy, doubles, doubles, doubles, doubles, dump, entropyOfInt, entropyOfLong, fallbackSetSeedIfInitialized, gaussians, gaussians, getEntropyBits, getRandomSeeder, initTransientFields, internalNextGaussian, ints, ints, ints, ints, lockForNextGaussian, longs, longs, longs, longs, nextDouble, nextDouble, nextDouble, nextElement, nextElement, nextEnum, nextInt, nextLong, nextLong, nextLong, setRandomSeeder, setSeed, unlockForNextGaussian, withProbability, withProbabilityInternal

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface io.github.pr0methean.betterrandom.EntropyCountingRandom

needsReseedingEarly

Constructor Detail

RandomWrapper

public RandomWrapper(T wrapped)

Creates an instance wrapping the given Random.

Parameters:

wrapped - the Random to wrap

Method Detail

wrapJavaUtilRandom

public static RandomWrapper<Random> wrapJavaUtilRandom(long seed)

Creates an instance wrapping a basic Random.

Parameters:

seed - the seed

Returns:

an instance

wrapJavaUtilRandom

public static RandomWrapper<Random> wrapJavaUtilRandom(byte[] seed)

Creates an instance wrapping a basic Random.

Parameters:

seed - the seed; must be 8 bytes

Returns:

an instance

wrapSecureRandom

public static RandomWrapper<SecureRandom> wrapSecureRandom(byte[] seed)

Creates an instance wrapping a basic SecureRandom with a given seed.

Parameters:

seed - the seed

Returns:

an instance

wrapJavaUtilRandom

public static RandomWrapper<Random> wrapJavaUtilRandom(SeedGenerator seedGenerator)
                                                throws SeedException

Creates an instance wrapping a basic Random.

Parameters:

seedGenerator - the generator used to generate the seed

Returns:

an instance

Throws:

SeedException - if seedGenerator failed to generate the initial seed

setInitiallyKnownSeed

protected void setInitiallyKnownSeed(byte[] seed)

Updates BaseRandom.seed and BaseRandom.entropyBits without reseeding the wrapped PRNG. Called by the wrapJavaUtilRandom overloads that take the seed as a parameter, since the seed isn't available from the PRNG once it's been passed to the constructor.

Parameters:

seed - the seed

toString

public String toString()

Overrides:

toString in class Object

usesParallelStreams

public boolean usesParallelStreams()

Overrides:

usesParallelStreams in class BaseRandom

Returns:

true if this PRNG creates parallel streams; false otherwise.

next

protected int next(int bits)

Description copied from class: BaseRandom

Generates the next pseudorandom number. Called by all other random-number-generating methods. Should not debit the entropy count, since that's done by the calling methods according to the amount they actually output (see for example BaseRandom.withProbability(double), which uses 53 random bits but outputs only one, and thus debits only 1 bit of entropy).

Specified by:

next in class BaseRandom

getWrapped

public T getWrapped()

Returns the PRNG this RandomWrapper is currently wrapping.

Returns:

the wrapped Random instance

setWrapped

public void setWrapped(T wrapped)

Replaces the wrapped PRNG with the given one on subsequent calls.

Parameters:

wrapped - an Random instance to wrap

addSubclassFields

protected MoreObjects.ToStringHelper addSubclassFields(MoreObjects.ToStringHelper original)

Description copied from class: BaseRandom

Adds the fields that were not inherited from BaseRandom to the given MoreObjects.ToStringHelper for dumping.

Specified by:

addSubclassFields in class BaseRandom

Parameters:

original - a MoreObjects.ToStringHelper object.

Returns:

original with the fields not inherited from BaseRandom written to it.

getSeed

public byte[] getSeed()

Returns the wrapped PRNG's seed, if we know it. When this RandomWrapper is wrapping a passed-in Random that's not a RepeatableRandom, we won't know the seed until the next BaseRandom.setSeed(byte[]) or setSeed(long) call lets us set it ourselves, and so an UnsupportedOperationException will be thrown until then.

Specified by:

getSeed in interface RepeatableRandom

Overrides:

getSeed in class BaseRandom

Returns:

The seed data used to initialize this pseudo-random number generator.

Throws:

UnsupportedOperationException - if this RandomWrapper doesn't know the wrapped PRNG's seed.

setSeed

public void setSeed(long seed)

Description copied from class: BaseRandom

Sets the seed of this random number generator using a single long seed, if this implementation supports that. If it is capable of using 64 bits or less of seed data (i.e. if {@link #getNewSeedLength()} <= {@link Long#BYTES}), then this method shall replace the entire seed as Random.setSeed(long) does; otherwise, it shall either combine the input with the existing seed as SecureRandom.setSeed(long) does, or it shall generate a new seed using the DefaultSeedGenerator. The latter is a backward-compatibility measure and can be very slow.

Overrides:

setSeed in class BaseRandom

See Also:

ByteArrayReseedableRandom.preferSeedWithLong()

setSeedInternal

protected void setSeedInternal(byte[] seed)

Delegates to one of ByteArrayReseedableRandom.setSeed(byte[]), SecureRandom.setSeed(byte[]) or Random.setSeed(long).

Overrides:

setSeedInternal in class BaseRandom

Parameters:

seed - The new seed.

supportsMultipleSeedLengths

protected boolean supportsMultipleSeedLengths()

Description copied from class: BaseRandom

If true, the subclass takes responsibility for checking whether the seed is non-null and has a valid length, and should throw an IllegalArgumentException in BaseRandom.setSeedInternal(byte[]) if not.

Overrides:

supportsMultipleSeedLengths in class BaseRandom

Returns:

true if this PRNG supports seed lengths other than BaseRandom.getNewSeedLength(); false otherwise.

preferSeedWithLong

public boolean preferSeedWithLong()

Description copied from interface: ByteArrayReseedableRandom

Indicates whether Random.setSeed(long) is recommended over ByteArrayReseedableRandom.setSeed(byte[]) when the seed is already in the form of a long.

Specified by:

preferSeedWithLong in interface ByteArrayReseedableRandom

Overrides:

preferSeedWithLong in class BaseRandom

Returns:

true if Random.setSeed(long) will tend to perform better than ByteArrayReseedableRandom.setSeed(byte[]).

getNewSeedLength

public int getNewSeedLength()

Description copied from interface: ByteArrayReseedableRandom

Returns the preferred length of a new byte-array seed. "Preferred" is implementation-defined when multiple seed lengths are supported, but should probably usually mean the longest one, since the longer the seed, the more random the output.

Specified by:

getNewSeedLength in interface ByteArrayReseedableRandom

Specified by:

getNewSeedLength in class BaseRandom

Returns:

The desired length of a new byte-array seed.

nextBytes

public void nextBytes(byte[] bytes)

Description copied from class: BaseRandom

Generates random bytes and places them into a user-supplied byte array. The number of random bytes produced is equal to the length of the byte array. Reimplemented for entropy-counting purposes.

Overrides:

nextBytes in class BaseRandom

nextInt

public int nextInt()

Overrides:

nextInt in class BaseRandom

nextInt

public int nextInt(int bound)

Overrides:

nextInt in class BaseRandom

nextLongNoEntropyDebit

protected long nextLongNoEntropyDebit()

Description copied from class: BaseRandom

Returns the next random long, but does not debit entropy.

Overrides:

nextLongNoEntropyDebit in class BaseRandom

Returns:

a pseudorandom long with all possible values equally likely.

nextBoolean

public boolean nextBoolean()

Overrides:

nextBoolean in class BaseRandom

nextFloat

public float nextFloat()

Overrides:

nextFloat in class BaseRandom

nextDoubleNoEntropyDebit

public double nextDoubleNoEntropyDebit()

Description copied from class: BaseRandom

Returns the next random double between 0.0 (inclusive) and 1.0 (exclusive), but does not debit entropy.

Overrides:

nextDoubleNoEntropyDebit in class BaseRandom

Returns:

a pseudorandom double.

nextGaussian

public double nextGaussian()

Description copied from class: BaseRandom

Returns the next pseudorandom, Gaussian ("normally") distributed double value with mean 0.0 and standard deviation 1.0 from this random number generator's sequence. Unlike the one in Random, this implementation is lockless.

Overrides:

nextGaussian in class BaseRandom