com.h3c.util

## Class ByteArrayGenerator

- java.lang.Object
- - com.h3c.util.ByteArrayGenerator

-     public class ByteArrayGenerator
      extends Object

  Generates byte arrays, either randomly, or via an iterator. The possible values that the arrays are initialized with are constrained by a "specification" that describes what values each element of the array can possibly take.

  Instances of this class are created via the factory methods `create(java.lang.String)` and `createFromHex(java.lang.String)`. Once you have an instance, each call to `generate()` will create a newly instantiated byte array initialized randomly as per the construction specification.

  Given an instance, you can ask it to create a byte array with the `lowest()` or `highest()` values defined by the specification, as well as ask `how many` possible arrays could be generated. You can also obtain an `iterator()` which will iterate from the lowest to highest values defined by the specification.

  Given two instances, you can see whether one is a `superset` of the other, or if the two `intersect`.

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `contains(byte[] b)` Returns `true` if the specified byte array can be generated by this byte array generator.
    `static ByteArrayGenerator` | `create(String spec)` Creates an instance of `ByteArrayGenerator` that will generate byte arrays within the constraints defined by the given specification.
    `static ByteArrayGenerator` | `createFromHex(String spec)` Creates an instance of `ByteArrayGenerator` that will generate byte arrays within the constraints defined by the given specification.
    `boolean` | `equals(Object o)`
    `byte[]` | `generate()` Creates and returns a new byte array populated with random data as per the specification.
    `String` | `getNormalizedSpec()` Returns a normalized specification string; that is to say, the bytes are expressed in lowercase hex, and instances of `00-ff` are replaced with `'*'`.
    `String` | `getSpec()` Returns the specification string with which this generator was initialized.
    `int` | `hashCode()`
    `byte[]` | `highest()` Returns an array with the byte values set to their highest values.
    `boolean` | `intersects(ByteArrayGenerator other)` Returns `true` if this byte array generator intersects the other byte array generator; false otherwise.
    `boolean` | `isSuperset(ByteArrayGenerator other)` Returns `true` if this byte array generator is a superset of the other byte array generator; false otherwise.
    `Iterator<byte[]>` | `iterator()` Returns an iterator that starts with the lowest specified value for the byte array and iterates through to the highest specified value, returning `resultSpaceSize` byte arrays in total.
    `byte[]` | `lowest()` Returns an array with the byte values set to their lowest values.
    `BigInteger` | `resultSpaceSize()` Returns the total number of possible arrays that could be generated by this array generator.
    `int` | `size()` Returns the "size" of this generator; that is, how many bytes in each generated array.
    `String` | `toDebugString()` Returns a multi-line string representation with information suitable for debugging.
    `String` | `toString()`

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Method Detail

    - #### size

          public int size()

      Returns the "size" of this generator; that is, how many bytes in each generated array.
      Returns:
        the size

    - #### getSpec

          public String getSpec()

      Returns the specification string with which this generator was initialized.
      Returns:
        the spec

    - #### getNormalizedSpec

          public String getNormalizedSpec()

      Returns a normalized specification string; that is to say, the bytes are expressed in lowercase hex, and instances of `00-ff` are replaced with `'*'`. For example, the generators created with the following:

           create("254:12:0-255:0-255")
           createFromHex("FE:0C:00-FF:00-FF")
           createFromHex("fe:c:*:*")

      all return the same (normalized) byte spec:

           "fe:0c:*:*"

      Returns:
        the normalized byte specification string

    - #### generate

          public byte[] generate()

      Creates and returns a new byte array populated with random data as per the specification.
      Returns:
        a new byte array with pseudo-random data in it

    - #### lowest

          public byte[] lowest()

      Returns an array with the byte values set to their lowest values.
      Returns:
        an array with the lowest values

    - #### highest

          public byte[] highest()

      Returns an array with the byte values set to their highest values.
      Returns:
        an array with the highest values

    - #### resultSpaceSize

          public BigInteger resultSpaceSize()

      Returns the total number of possible arrays that could be generated by this array generator.
      Returns:
        the total number of possible arrays

    - #### iterator

          public Iterator<byte[]> iterator()

      Returns an iterator that starts with the lowest specified value for the byte array and iterates through to the highest specified value, returning `resultSpaceSize` byte arrays in total.
      Returns:
        an iterator

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### toDebugString

          public String toDebugString()

      Returns a multi-line string representation with information suitable for debugging.
      Returns:
        a multi-line string representation

    - #### equals

          public boolean equals(Object o)

      Overrides:
        `equals` in class `Object`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### isSuperset

          public boolean isSuperset(ByteArrayGenerator other)

      Returns `true` if this byte array generator is a superset of the other byte array generator; false otherwise. Put another way, the set of all possible byte arrays produced by the other generator is a subset of the set of all possible byte arrays produced by this generator.
      Parameters:
        `other` - the other generator to compare with
      Returns:
        true if this generator is a superset of the other generator; false otherwise
      Throws:
        `IllegalArgumentException` - if other generator is not the same size as this one
        `NullPointerException` - if other is null

    - #### contains

          public boolean contains(byte[] b)

      Returns `true` if the specified byte array can be generated by this byte array generator.
      Parameters:
        `b` - the byte array
      Returns:
        true if this generator can generate a byte array with this value; false otherwise

    - #### intersects

          public boolean intersects(ByteArrayGenerator other)

      Returns `true` if this byte array generator intersects the other byte array generator; false otherwise. Put another way, this predicate returns true if the set of all possible byte arrays produced by this generator contains any byte array that could possibly be generated by the other generator.
      Parameters:
        `other` - the other generator to compare with
      Returns:
        true if this generator intersects the other generator; false otherwise
      Throws:
        `IllegalArgumentException` - if the other generator is not the same size as this one
        `NullPointerException` - if other is null

    - #### create

          public static ByteArrayGenerator create(String spec)

      Creates an instance of `ByteArrayGenerator` that will generate byte arrays within the constraints defined by the given specification. Specifications are declared with decimal values.

      spec is a colon delimited string of the following form:

            {byteSpec} [ : {byteSpec} [ ... ] ]

      where byteSpec represents a single byte in the array, and is of the form:

           {n} | {n}-{m} | *

      where n and m are integers in the range 0 to 255, m (when specified) is > n, and * represents 0-255.

      For example, the specification `"15:1:0-30:100-255"` declares that the generator should return byte arrays 4 bytes in length, where the first byte (index = 0) is always 15, the second byte (index = 1) is always 1, the third byte is drawn randomly from the range 0 .. 30, and the last byte is drawn randomly from the range 100 .. 255.

      Another example, the specification `"0-255:0-255"` declares that the generator should return byte arrays 2 bytes in length, with both bytes being any randomly chosen value. This specification could also be written `"*:*"`

      Parameters:
        `spec` - the specification
      Returns:
        a byte array generator
      Throws:
        `IllegalArgumentException` - if spec is ill-formed

    - #### createFromHex

          public static ByteArrayGenerator createFromHex(String spec)

      Creates an instance of `ByteArrayGenerator` that will generate byte arrays within the constraints defined by the given specification. Specifications are declared with hex values.

      Spec is a colon delimited string of the following form:

            {byteSpec} [ : {byteSpec} [ ... ] ]

      where byteSpec represents a single byte in the array, and is of the form:

           {n} | {n}-{m} | *

      where n and m are hex values in the range 0 to FF, m (when specified) is > n, and * represents `0-FF`. Upper- or lower- case hex digits are allowed.

      For example, the specification `"F:1:0-1E:C8-FF"` declares that the generator should return byte arrays 4 bytes in length, where the first byte (index = 0) is always F (15), the second byte (index = 1) is always 1, the third byte is drawn randomly from the range 0 .. 1E (0 .. 30), and the last byte is drawn randomly from the range C8 .. FF (200 .. 255).

      Another example, the specification `"00-FF:00-FF"` declares that the generator should return byte arrays 2 bytes in length, with both bytes being any randomly chosen value. This specification could also be written `"*:*"`

      Parameters:
        `spec` - the specification
      Returns:
        a byte array generator
      Throws:
        `IllegalArgumentException` - if spec is ill-formed

Copyright © 2014. All Rights Reserved.