student

Class TestableRandom

java.lang.Object

java.util.Random

student.TestableRandom

All Implemented Interfaces:

Serializable

public class TestableRandom
extends Random

This subclass of Random adds extra methods useful for testing purposes. Normally, you might generate a new random number by calling nextInt(), nextDouble(), or one of the other generation methods provided by Random. Normally, this intentionally makes your code behave in a random way, which may make it harder to test. This class allows you to control directly the sequence of numbers that will be generated by such calls.

Suppose your code is written this way:

  Random random = new TestableRandom();
  ...
  int x = random.nextInt(64);
  

You can then write test cases that look like this:

  public void testSomeFeature()
  {
      // Set the return values for the next 6 calls to nextInt(),
      // No matter which instance of TestableRandom the method is called on
      TestableRandom.setNextInts(5, 10, 22, 13, 12, 47);

      // Perform tests, knowing in advance the exact sequence of numbers
      // That will now be generated
  }
  

This class provides separate methods to preset the sequence of booleans, ints, doubles, floats, bytes, or Gaussian-distributed doubles that will be generated. You can pass in as many specific values to the setNext...() methods that you like, or you can even pass in an array:

  int[] someValues = new int[] { 1, 2, 3, 4, 5, 6, 7 };
  TestableRandom.setNextInts(someValues);
  

Version:

$Revision: 1.3 $, $Date: 2010/02/25 19:27:24 $

Author:

Stephen Edwards, Last changed by $Author: stedwar2 $

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
TestableRandom() Creates a new random number generator.
TestableRandom(long seed) Creates a new random number generator using a single long seed.

Method Summary

Modifier and Type	Method and Description
boolean	nextBoolean() Returns the next pseudorandom, uniformly distributed boolean value from this random number generator's sequence.
void	nextBytes(byte[] bytes) Generates random bytes and places them into a user-supplied byte array.
double	nextDouble() Returns the next pseudorandom, uniformly distributed double value between 0.0 and 1.0 from this random number generator's sequence.
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() Returns the next pseudorandom, uniformly distributed int value from this random number generator's sequence.
int	nextInt(int n) Returns a pseudorandom, uniformly distributed int value between 0 (inclusive) and the specified value (exclusive), drawn from this random number generator's sequence.
long	nextLong() Returns the next pseudorandom, uniformly distributed long value from this random number generator's sequence.
static void	setNextBooleans(boolean... values) This method allows one to provide a predefined series of values that will override the results provided by nextBoolean().
static void	setNextBytes(byte... values) This method allows one to provide a predefined series of values that will override the results provided by nextBytes(byte[]).
static void	setNextDoubles(double... values) This method allows one to provide a predefined series of values that will override the results provided by nextDouble().
static void	setNextFloats(float... values) This method allows one to provide a predefined series of values that will override the results provided by Random.nextFloat().
static void	setNextGaussians(double... values) This method allows one to provide a predefined series of values that will override the results provided by nextGaussian().
static void	setNextInts(int... values) This method allows one to provide a predefined series of values that will override the results provided by nextInt() and nextInt(int).
static void	setNextLongs(long... values) This method allows one to provide a predefined series of values that will override the results provided by nextLong().

Methods inherited from class java.util.Random

doubles, doubles, doubles, doubles, ints, ints, ints, ints, longs, longs, longs, longs, next, nextFloat, setSeed

Methods inherited from class java.lang.Object

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

Constructor Detail

TestableRandom

public TestableRandom()

Creates a new random number generator. This constructor sets the seed of the random number generator to a value very likely to be distinct from any other invocation of this constructor.

TestableRandom

public TestableRandom(long seed)

Creates a new random number generator using a single long seed. The seed is the initial value of the internal state of the pseudorandom number generator which is maintained by method Random.next(int).

The invocation new Random(seed) is equivalent to:

 Random rnd = new Random();
 rnd.setSeed(seed);
 

Parameters:

seed - the initial seed

See Also:

Random.setSeed(long)

Method Detail

setNextInts

public static void setNextInts(int... values)

This method allows one to provide a predefined series of values that will override the results provided by nextInt() and nextInt(int). This is useful during testing, when you want to control the results generated by a random number generator. If you do not use this method, nextInt() and nextInt(int) behave normally.

Note that the sequence of int values you provide will be shared by all instances of this class--so, no matter how many TestableRandom instances you have created, the sequence of random numbers generated by calls to their methods will be determined by what you pass in here.

If previous values from an earlier call to this method have not yet been used, they will be replaced by any parameters you provide in the next call to this method. If previous values from an earlier call to this method have not yet been used, and you provide no arguments in your next call to this method, those unused values will be replaced with nothing, so normal pseudorandom generation behavior will resume immediately.

Parameters:

values - a sequence of int values to use as the results in subsequent calls to nextInt() or nextInt(int)

setNextLongs

public static void setNextLongs(long... values)

This method allows one to provide a predefined series of values that will override the results provided by nextLong(). This is useful during testing, when you want to control the results generated by a random number generator. If you do not use this method, nextLong() behaves normally.

Note that the sequence of long values you provide will be shared by all instances of this class--so, no matter how many TestableRandom instances you have created, the sequence of random numbers generated by calls to their methods will be determined by what you pass in here.

If previous values from an earlier call to this method have not yet been used, they will be replaced by any parameters you provide in the next call to this method. If previous values from an earlier call to this method have not yet been used, and you provide no arguments in your next call to this method, those unused values will be replaced with nothing, so normal pseudorandom generation behavior will resume immediately.

Parameters:

values - a sequence of long values to use as the results in subsequent calls to nextLong()

setNextBooleans

public static void setNextBooleans(boolean... values)

This method allows one to provide a predefined series of values that will override the results provided by nextBoolean(). This is useful during testing, when you want to control the results generated by a random number generator. If you do not use this method, nextBoolean() behaves normally.

Note that the sequence of boolean values you provide will be shared by all instances of this class--so, no matter how many TestableRandom instances you have created, the sequence of random booleans generated by calls to their methods will be determined by what you pass in here.

If previous values from an earlier call to this method have not yet been used, they will be replaced by any parameters you provide in the next call to this method. If previous values from an earlier call to this method have not yet been used, and you provide no arguments in your next call to this method, those unused values will be replaced with nothing, so normal pseudorandom generation behavior will resume immediately.

Parameters:

values - a sequence of boolean values to use as the results in subsequent calls to nextBoolean()

setNextFloats

public static void setNextFloats(float... values)

This method allows one to provide a predefined series of values that will override the results provided by Random.nextFloat(). This is useful during testing, when you want to control the results generated by a random number generator. If you do not use this method, Random.nextFloat() behaves normally.

Note that the sequence of float values you provide will be shared by all instances of this class--so, no matter how many TestableRandom instances you have created, the sequence of random numbers generated by calls to their methods will be determined by what you pass in here.

If previous values from an earlier call to this method have not yet been used, they will be replaced by any parameters you provide in the next call to this method. If previous values from an earlier call to this method have not yet been used, and you provide no arguments in your next call to this method, those unused values will be replaced with nothing, so normal pseudorandom generation behavior will resume immediately.

Parameters:

values - a sequence of float values to use as the results in subsequent calls to Random.nextFloat()

setNextDoubles

public static void setNextDoubles(double... values)

This method allows one to provide a predefined series of values that will override the results provided by nextDouble(). This is useful during testing, when you want to control the results generated by a random number generator. If you do not use this method, nextDouble() behaves normally.

Note that the sequence of double values you provide will be shared by all instances of this class--so, no matter how many TestableRandom instances you have created, the sequence of random numbers generated by calls to their methods will be determined by what you pass in here.

If previous values from an earlier call to this method have not yet been used, they will be replaced by any parameters you provide in the next call to this method. If previous values from an earlier call to this method have not yet been used, and you provide no arguments in your next call to this method, those unused values will be replaced with nothing, so normal pseudorandom generation behavior will resume immediately.

Parameters:

values - a sequence of double values to use as the results in subsequent calls to nextDouble()

setNextGaussians

public static void setNextGaussians(double... values)

This method allows one to provide a predefined series of values that will override the results provided by nextGaussian(). This is useful during testing, when you want to control the results generated by a random number generator. If you do not use this method, nextGaussian() behaves normally.

Note that the sequence of double values you provide will be shared by all instances of this class--so, no matter how many TestableRandom instances you have created, the sequence of random numbers generated by calls to their methods will be determined by what you pass in here.

If previous values from an earlier call to this method have not yet been used, they will be replaced by any parameters you provide in the next call to this method. If previous values from an earlier call to this method have not yet been used, and you provide no arguments in your next call to this method, those unused values will be replaced with nothing, so normal pseudorandom generation behavior will resume immediately.

Parameters:

values - a sequence of double values to use as the results in subsequent calls to nextGaussian()

setNextBytes

public static void setNextBytes(byte... values)

This method allows one to provide a predefined series of values that will override the results provided by nextBytes(byte[]). This is useful during testing, when you want to control the results generated by a random number generator. If you do not use this method, nextBytes(byte[]) behaves normally.

Note that the sequence of byte values you provide will be shared by all instances of this class--so, no matter how many TestableRandom instances you have created, the sequence of random numbers generated by calls to their methods will be determined by what you pass in here.

If previous values from an earlier call to this method have not yet been used, they will be replaced by any parameters you provide in the next call to this method. If previous values from an earlier call to this method have not yet been used, and you provide no arguments in your next call to this method, those unused values will be replaced with nothing, so normal pseudorandom generation behavior will resume immediately.

Parameters:

values - a sequence of byte values to use as the results in subsequent calls to nextBytes(byte[])

nextInt

public int nextInt()

Returns the next pseudorandom, uniformly distributed int value from this random number generator's sequence. The general contract of nextInt is that one int value is pseudorandomly generated and returned. All 2³² possible int values are produced with (approximately) equal probability.

If setNextInts(int...) has been called, the next available value from the provided sequence will be returned until that sequence is exhausted. One all provided values have been returned, then true pseudorandom generation will resume.

Overrides:

nextInt in class Random

Returns:

the next pseudorandom, uniformly distributed int value from this random number generator's sequence

nextInt

public int nextInt(int n)

Returns a pseudorandom, uniformly distributed int value between 0 (inclusive) and the specified value (exclusive), drawn from this random number generator's sequence. The general contract of nextInt is that one int value in the specified range is pseudorandomly generated and returned. All n possible int values are produced with (approximately) equal probability.

If setNextInts(int...) has been called, the next available value from the provided sequence (modulo n) will be returned until that sequence is exhausted. One all provided values have been returned, then true pseudorandom generation will resume.

Overrides:

nextInt in class Random

Parameters:

n - the bound on the random number to be returned. Must be positive.

Returns:

the next pseudorandom, uniformly distributed int value between 0 (inclusive) and n (exclusive) from this random number generator's sequence

Throws:

IllegalArgumentException - if n is not positive

nextLong

public long nextLong()

Returns the next pseudorandom, uniformly distributed long value from this random number generator's sequence. The general contract of nextLong is that one long value is pseudorandomly generated and returned.

If setNextLongs(long...) has been called, the next available value from the provided sequence will be returned until that sequence is exhausted. One all provided values have been returned, then true pseudorandom generation will resume.

Overrides:

nextLong in class Random

Returns:

the next pseudorandom, uniformly distributed long value from this random number generator's sequence

nextBoolean

public boolean nextBoolean()

Returns the next pseudorandom, uniformly distributed boolean value from this random number generator's sequence. The general contract of nextBoolean is that one boolean value is pseudorandomly generated and returned. The values true and false are produced with (approximately) equal probability.

If setNextBooleans(boolean...) has been called, the next available value from the provided sequence will be returned until that sequence is exhausted. One all provided values have been returned, then true pseudorandom generation will resume.

Overrides:

nextBoolean in class Random

Returns:

the next pseudorandom, uniformly distributed boolean value from this random number generator's sequence

nextDouble

public double nextDouble()

Returns the next pseudorandom, uniformly distributed double value between 0.0 and 1.0 from this random number generator's sequence.

If setNextDoubles(double...) has been called, the next available value from the provided sequence will be returned until that sequence is exhausted. One all provided values have been returned, then true pseudorandom generation will resume.

Overrides:

nextDouble in class Random

Returns:

the next pseudorandom, uniformly distributed double value from this random number generator's sequence

nextGaussian

public 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.

If setNextGaussians(double...) has been called, the next available value from the provided sequence will be returned until that sequence is exhausted. One all provided values have been returned, then true pseudorandom generation will resume.

Overrides:

nextGaussian in class Random

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

nextBytes

public void nextBytes(byte[] bytes)

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.

If setNextBytes(byte...) has been called, unused values from the provided sequence will be used to fill the provided array until that sequence is exhausted. One all provided values have been used up, true pseudorandom generation will resume for filling any remaining slots in this or future calls.

Overrides:

nextBytes in class Random

Parameters:

bytes - the byte array to fill with random bytes

Throws:

NullPointerException - if the byte array is null