org.licas.data.gen

## Class DataGenerator

- java.lang.Object
- - org.licas.data.gen.DataGenerator

- Direct Known Subclasses:
    NumberDataGenerator, ObjectDataGenerator, StringDataGenerator

      public abstract class DataGenerator
      extends java.lang.Object

  This defines the methods that should be implemented by a data generator. The generator is initialised with a random number generator seed. This is required to be done externally so that multiple instances can have different seed values. If a random number generator is not used, then the value can be null (0).
  Author:
    Kieran Greer

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected org.licas_xml.abs.Element` | `adminXml` An admin document might have been passed through the constructor
    `protected java.lang.String` | `dataType` The data type
    `protected java.lang.String` | `maxValue` The maximum allowed value
    `protected java.lang.String` | `minValue` The minimum allowed value
    `protected java.util.Random` | `rnd` The random number generator
    `protected long` | `seed` A seed value that can be used to initialise a random number generator

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `DataGenerator(org.licas_xml.abs.Element adminXml)` Create a new instance of DataGenerator.
    `DataGenerator(long thisSeed, java.lang.String thisDataType)` Create a new instance of DataGenerator, ignoring the base service features.

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static org.licas_xml.abs.Element` | `conditionsToXml(BehaviourScript testScript, long rndSeed)` Create an XML script that can be used to initialise an instance of the derived class.
    `static org.licas_xml.abs.Element` | `conditionsToXml(int index, BehaviourScript testScript, long rndSeed)` Create an XML script that can be used to initialise an instance of the derived class.
    `static org.licas_xml.abs.Element` | `conditionsToXml(java.lang.String dataType, double minValue, double maxValue, java.lang.String dataCondition, long rndSeed)` Create an XML script that can be used to initialise an instance of the derived class.
    `static java.lang.String` | `generateStringRange(int stringLength)` Generate the new data range.
    `protected org.licas_xml.abs.Element` | `getBaseElement(org.licas_xml.abs.Element adminXml)` Get the base data generator element from the admin document element.
    `java.lang.String` | `getDataType()` Get the data type created by this generator.
    `static java.lang.String` | `getGeneratorClass(java.lang.String dataType)` Get the generator class for the specified data type.
    `abstract java.lang.Object` | `getNextValue()` Generate the next data value.
    `static boolean` | `isAllowedDataType(java.lang.String generator, java.lang.String theDataType)` This method creates a data generator of the specified type and checks if the data type entered is allowed.
    `abstract void` | `parseGenXml(org.licas_xml.abs.Element genXml)` Parse the data generator script to set the appropriate variable values.
    `void` | `setMaxValue(java.lang.String thisValue)` Set the maximum value for data generation.
    `void` | `setMinValue(java.lang.String thisValue)` Set the minimum value for data generation.

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

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

- - ### Field Detail

    - #### dataType

          protected java.lang.String dataType

      The data type

    - #### seed

          protected long seed

      A seed value that can be used to initialise a random number generator

    - #### minValue

          protected java.lang.String minValue

      The minimum allowed value

    - #### maxValue

          protected java.lang.String maxValue

      The maximum allowed value

    - #### adminXml

          protected org.licas_xml.abs.Element adminXml

      An admin document might have been passed through the constructor

    - #### rnd

          protected java.util.Random rnd

      The random number generator

  - ### Constructor Detail

    - #### DataGenerator

          public DataGenerator(long thisSeed,
                               java.lang.String thisDataType)

      Create a new instance of DataGenerator, ignoring the base service features.
      Parameters:
        `thisDataType` - the generator data type.
        `thisSeed` - to seed a random number generator. Can be 0 if not used.

    - #### DataGenerator

          public DataGenerator(org.licas_xml.abs.Element adminXml)
                        throws java.lang.Exception

      Create a new instance of DataGenerator.
      Parameters:
        `adminXml` - a script including the value ranges for the data. This would now be a full admin script, with an `Const`.`PARAMETERS` section for these values.
      Throws:
        `java.lang.Exception` - any error.

  - ### Method Detail

    - #### parseGenXml

          public abstract void parseGenXml(org.licas_xml.abs.Element genXml)
                                    throws java.lang.Exception

      Parse the data generator script to set the appropriate variable values.
      Parameters:
        `genXml` - the script to parse
      Throws:
        `java.lang.Exception` - any error.

    - #### getNextValue

          public abstract java.lang.Object getNextValue()
                                                 throws java.lang.Exception

      Generate the next data value.
      Returns:
        the next randomly generated data value.
      Throws:
        `java.lang.Exception` - any error.

    - #### getBaseElement

          protected org.licas_xml.abs.Element getBaseElement(org.licas_xml.abs.Element adminXml)

      Get the base data generator element from the admin document element.
      Parameters:
        `adminXml` - the constructor document. Should contain other child elements.
      Returns:
        the base element with the data generator description, if not this one.

    - #### setMinValue

          public void setMinValue(java.lang.String thisValue)

      Set the minimum value for data generation.
      Parameters:
        `thisValue` - the minimum value. This needs to then be converted to the actual value type.

    - #### setMaxValue

          public void setMaxValue(java.lang.String thisValue)

      Set the maximum value for data generation.
      Parameters:
        `thisValue` - the maximum value. This needs to then be converted to the actual value type.

    - #### getDataType

          public java.lang.String getDataType()

      Get the data type created by this generator. This could be a simple type or a complex object class name.
      Returns:
        the value of dataType.

    - #### isAllowedDataType

          public static boolean isAllowedDataType(java.lang.String generator,
                                                  java.lang.String theDataType)

      This method creates a data generator of the specified type and checks if the data type entered is allowed. Only the default generators can be checked.
      Parameters:
        `generator` - the generator class name.
        `theDataType` - the data type class name.
      Returns:
        true if the generator can generate data of the specified type. If the generator is not known, true is returned by default.

    - #### getGeneratorClass

          public static java.lang.String getGeneratorClass(java.lang.String dataType)

      Get the generator class for the specified data type.
      Parameters:
        `dataType` - the data type class name.
      Returns:
        the class name of the generator that would create data of the specified type. The `ObjectDataGenerator` class is returned if there is no match.

    - #### conditionsToXml

          public static org.licas_xml.abs.Element conditionsToXml(BehaviourScript testScript,
                                                                  long rndSeed)

      Create an XML script that can be used to initialise an instance of the derived class. This method can create an xml script for the data generators available as part of the base licas package only and assumes no additional initialisation conditions.
      Parameters:
        `testScript` - the test script with the config information.
        `rndSeed` - a seed for a random number generator if required. Can be 0.
      Returns:
        an XML script that describes the conditions.

    - #### conditionsToXml

          public static org.licas_xml.abs.Element conditionsToXml(int index,
                                                                  BehaviourScript testScript,
                                                                  long rndSeed)

      Create an XML script that can be used to initialise an instance of the derived class. This method can create an xml script for the data generators available as part of the base licas package only.
      Parameters:
        `index` - a data index can be included for retrieving a string-based data condition from the script, specifically, a `testScript.dataConditions` element.
        `testScript` - the test script with the config information.
        `rndSeed` - a seed for a random number generator if required. Can be 0.
      Returns:
        an XML script that describes the conditions.

    - #### conditionsToXml

          public static org.licas_xml.abs.Element conditionsToXml(java.lang.String dataType,
                                                                  double minValue,
                                                                  double maxValue,
                                                                  java.lang.String dataCondition,
                                                                  long rndSeed)

      Create an XML script that can be used to initialise an instance of the derived class. This method can create an xml script for the data generators available as part of the base licas package only.
      Parameters:
        `dataType` - the data type class name.
        `minValue` - minimum value for the data generator.
        `maxValue` - maximum value for the data generator.
        `dataCondition` - condition under which data can be generated. Can be null or empty for a default setting.
        `rndSeed` - a seed for a random number generator if required. Can be 0.
      Returns:
        an XML script that describes the conditions.

    - #### generateStringRange

          public static java.lang.String generateStringRange(int stringLength)

      Generate the new data range. This is a string-based value.
      Parameters:
        `stringLength` - the length of the string to generate.
      Returns:
        a randomly generated sequence of characters.