Package edu.berkeley.cs.jqf.fuzz.guidance

Class StreamBackedRandom

java.lang.Object
java.util.Random
edu.berkeley.cs.jqf.fuzz.guidance.StreamBackedRandom
All Implemented Interfaces:
Serializable, java.util.random.RandomGenerator
public class StreamBackedRandom extends Random
This class extends Random to act as a generator of "random" values, which themselves are read from a static file. The file-backed random number generator can be used for tuning the "random" choices made by various junit-quickcheck generators using a mutation-based genetic algorithm, in order to maximize some objective function that can be measured from the execution of each trial, such as code coverage.
See Also:

  • Nested Class Summary

    Nested classes/interfaces inherited from interface java.util.random.RandomGenerator

    java.util.random.RandomGenerator.ArbitrarilyJumpableGenerator, java.util.random.RandomGenerator.JumpableGenerator, java.util.random.RandomGenerator.LeapableGenerator, java.util.random.RandomGenerator.SplittableGenerator, java.util.random.RandomGenerator.StreamableGenerator

  • Constructor Summary

    Constructors
    Constructor
    Description
    StreamBackedRandom(InputStream source)
    Constructs a stream-backed random generator.
    StreamBackedRandom(InputStream source, int leadinBytesToIgnore)
    Convenience constructor for use with the junit-quickcheck framework.

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    getTotalBytesRead()
     
    int
    next(int bits)
    Generates upto 32 bits of random data for internal use by the Random class.
    byte
    nextByte()
     
    int
    nextInt(int bound)
    Returns a pseudo-random value in the range [0, bound), consuming only as many whole bytes of the backing source as the bound requires.
    short
    nextShort()
     

    Methods inherited from class java.util.Random

    doubles, doubles, doubles, doubles, ints, ints, ints, ints, longs, longs, longs, longs, nextBoolean, nextBytes, nextDouble, nextFloat, nextGaussian, nextInt, nextLong, setSeed

    Methods inherited from class java.lang.Object

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

    Methods inherited from interface java.util.random.RandomGenerator

    isDeprecated, nextDouble, nextDouble, nextExponential, nextFloat, nextFloat, nextGaussian, nextInt, nextLong, nextLong

  • Constructor Details

    • StreamBackedRandom

      public StreamBackedRandom(InputStream source)
      Constructs a stream-backed random generator. Also sets the seed of the underlying pseudo-random number generator deterministically to zero.
      Parameters:
      source - a generator of "random" bytes

    • StreamBackedRandom

      public StreamBackedRandom(InputStream source, int leadinBytesToIgnore)
      Convenience constructor for use with the junit-quickcheck framework. The junit-quickcheck SourceOfRandomness annoyingly reads 8 bytes of random data as soon as it is instantiated, only to configure its own seed. As the seed is meaningless here, the 8 bytes get wasted. For this purpose, this constructor allows specifying how many bytes of requested random data to skip before starting to read from file.
      Parameters:
      source - a generator of "random" bytes
      leadinBytesToIgnore - the number of leading bytes to ignore

  • Method Details

    • next

      public int next(int bits)
      Generates upto 32 bits of random data for internal use by the Random class.

      Attempts to read up to 4 bytes of data from the input file, and returns the requested lower order bits as a pseudo-random value.

      If end-of-file is reached before reading 4 bytes, an IllegalStateException is thrown.

      Overrides:
      next in class Random
      Parameters:
      bits - the number of random bits to retain (1 to 32 inclusive)
      Returns:
      the integer value whose lower bits bits contain the next random data available in the backing source
      Throws:
      IllegalStateException - if EOF has already been reached

    • nextInt

      public int nextInt(int bound)
      Returns a pseudo-random value in the range [0, bound), consuming only as many whole bytes of the backing source as the bound requires.

      The original implementation always drew four bytes via next(31). For a small bound such as a byte or boolean range that wasted three of every four input bytes: the surplus bytes are read and then discarded by the modulo, so mutating them cannot change the result. Reading ceil(log2(bound)) bits rounded up to whole bytes keeps every consumed byte meaningful and shortens the input a mutation-based fuzzer has to explore.

      Specified by:
      nextInt in interface java.util.random.RandomGenerator
      Overrides:
      nextInt in class Random
      Parameters:
      bound - the exclusive upper bound; must be positive
      Returns:
      a value in [0, bound)
      Throws:
      IllegalArgumentException - if bound is not positive

    • nextByte

      public byte nextByte()

    • nextShort

      public short nextShort()

    • getTotalBytesRead

      public int getTotalBytesRead()