Package com.xceptance.xlt.api.data

# Class DataProvider

java.lang.Object
com.xceptance.xlt.api.data.DataProvider

public class DataProvider extends Object
The `DataProvider` class provides convenient access to a fixed set of test data strings, which is backed by a data file. Each line in the data file represents exactly one data item.

This class does a basic processing of comment lines, for example header lines that describe the data. All lines that start with the configured line comment marker are filtered out.

The specified data file is searched for in the XLT data directory, which is "config/data" in the test suite's home directory by default. You may change this directory by setting the XLT property "com.xceptance.xlt.data.directory" to an appropriate value.

Note: Be careful when creating instances of this class, as each instance loads the respective data file into memory. Typically, data providers can/should be shared among test users, so you should have to create just one instance. A simple way to ensure that there will be only one instance is to use the provided `getInstance(String)` factory method. But you are free to create (using the constructors) and manage the instances on your own.

See Also:
  - `GeneralDataProvider`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `DEFAULT`
  Languages supported.
  `static final String`
  `DEFAULT_FILE_ENCODING`
  The default file encoding ("UTF-8").
  `static final String`
  `DEFAULT_LINE_COMMENT_MARKER`
  The default line comment character ("#").

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DataProvider(String fileName)`
  Creates a new `DataProvider` instance and initializes it with the data loaded from the given data file.
  `DataProvider(String fileName, String encoding)`
  Creates a new `DataProvider` instance and initializes it with the data loaded from the given data file.
  `DataProvider(String fileName, String encoding, String lineCommentMarker)`
  Creates a new `DataProvider` instance and initializes it with the data loaded from the given data file.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addRow(int rowNumber, String row)`
  Adds a new data row at the specified row index to the internal store.
  `void`
  `addRow(String row)`
  Adds a new data row as the last element to the internal store.
  `List<String>`
  `getAllRows()`
  Returns all rows as an unmodifiable list to protect the data.
  `static DataProvider`
  `getInstance(String fileName)`
  Returns the data provider responsible for the given file name.
  `String`
  `getRandomRow()`
  Returns a randomly-chosen data row.
  `String`
  `getRandomRow(boolean removeWhitespace)`
  Returns a randomly-chosen data row.
  `String`
  `getRow(boolean removeWhitespace, int rowNumber)`
  Returns the specified data row.
  `String`
  `getRow(int rowNumber)`
  Returns the specified data row.
  `int`
  `getSize()`
  Returns the size of the data set.
  `protected List<String>`
  `loadData(File file, String encoding)`
  Loads the data lines from the given file into a list.
  `protected List<String>`
  `processLines(List<String> lines)`
  Post-processes the data lines just read.
  `String`
  `removeRow(int rowNumber)`
  Removes the data row with the specified row number from the internal store.
  `boolean`
  `removeRow(String row)`
  Removes the first occurrence of the specified data row from the internal store.

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

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

- ## Field Details

  - ### DEFAULT

    public static final String DEFAULT
    Languages supported.
    See Also:
      - Constant Field Values

  - ### DEFAULT_FILE_ENCODING

    public static final String DEFAULT_FILE_ENCODING
    The default file encoding ("UTF-8").
    See Also:
      - Constant Field Values

  - ### DEFAULT_LINE_COMMENT_MARKER

    public static final String DEFAULT_LINE_COMMENT_MARKER
    The default line comment character ("#").
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### DataProvider

    public DataProvider(String fileName) throws IOException, FileNotFoundException
    Creates a new `DataProvider` instance and initializes it with the data loaded from the given data file. The data file is expected to be saved using `DEFAULT_FILE_ENCODING`. Lines in the data file that start with the `DEFAULT_LINE_COMMENT_MARKER` are considered as comment lines.
    Parameters:
      `fileName` - the name/path of the data file
    Throws:
      `FileNotFoundException` - if the data file cannot be found
      `IOException` - if the data file cannot be opened or read

  - ### DataProvider

    public DataProvider(String fileName, String encoding) throws IOException, FileNotFoundException
    Creates a new `DataProvider` instance and initializes it with the data loaded from the given data file. The data file is expected to be saved using the passed encoding, for example "UTF-8" or "ISO-8859-1". Lines in the data file that start with the `DEFAULT_LINE_COMMENT_MARKER` are considered as comment lines.
    Parameters:
      `fileName` - the name/path of the data file
      `encoding` - the data file encoding
    Throws:
      `FileNotFoundException` - if the data file cannot be found
      `IOException` - if the data file cannot be opened or read

  - ### DataProvider

    public DataProvider(String fileName, String encoding, String lineCommentMarker) throws IOException, FileNotFoundException
    Creates a new `DataProvider` instance and initializes it with the data loaded from the given data file. The data file is expected to be saved using the passed encoding, for example "UTF-8" or "ISO-8859-1". Lines in the data file that start with the given line comment marker are considered as comment lines.
    Parameters:
      `fileName` - the name/path of the data file
      `encoding` - the data file encoding
      `lineCommentMarker` - the line comment marker to be used (may be `null`)
    Throws:
      `FileNotFoundException` - if the data file cannot be found
      `IOException` - if the data file cannot be opened or read

- ## Method Details

  - ### getInstance

    public static DataProvider getInstance(String fileName) throws FileNotFoundException, IOException
    Returns the data provider responsible for the given file name. If a data provider has not been requested yet for this file name, then a new data provider is created, otherwise the previously created provider will be returned. Note that the data providers will be initialized using `DEFAULT_FILE_ENCODING` and `DEFAULT_LINE_COMMENT_MARKER`.

    Use this method to ensure, that only a single data provider instance is created.

    Parameters:
      `fileName` - the file name/path of the data file
    Returns:
      the data provider
    Throws:
      `FileNotFoundException` - if the data file cannot be found
      `IOException` - if the data file cannot be opened or read

  - ### getAllRows

    public List<String> getAllRows()
    Returns all rows as an unmodifiable list to protect the data.
    Returns:
      all rows or an empty list, if no data is available

  - ### getRandomRow

    public String getRandomRow()
    Returns a randomly-chosen data row.
    Returns:
      a row, or `null` if the data set is empty

  - ### getRandomRow

    public String getRandomRow(boolean removeWhitespace)
    Returns a randomly-chosen data row.
    Parameters:
      `removeWhitespace` - whether all whitespace is to be removed from the data
    Returns:
      a row, or `null` if the data set is empty

  - ### getRow

    public String getRow(boolean removeWhitespace, int rowNumber)
    Returns the specified data row.
    Parameters:
      `removeWhitespace` - whether all whitespace is to be removed from the data
      `rowNumber` - the number of the row to read
    Returns:
      the row, or `null` if the specified row number exceeds the size of the data set

  - ### getRow

    public String getRow(int rowNumber)
    Returns the specified data row.
    Parameters:
      `rowNumber` - the number of the row to read
    Returns:
      the row, or `null` if the specified row number exceeds the size of the data set

  - ### addRow

    public void addRow(int rowNumber, String row)
    Adds a new data row at the specified row index to the internal store.
    Parameters:
      `rowNumber` - the index of the new row
      `row` - the new row

  - ### addRow

    public void addRow(String row)
    Adds a new data row as the last element to the internal store.
    Parameters:
      `row` - the new row

  - ### removeRow

    public String removeRow(int rowNumber)
    Removes the data row with the specified row number from the internal store.
    Parameters:
      `rowNumber` - the index of the row to remove
    Returns:
      the row just removed, or `null` if the specified row number exceeds the size of the data set

  - ### removeRow

    public boolean removeRow(String row)
    Removes the first occurrence of the specified data row from the internal store.
    Parameters:
      `row` - the row to remove
    Returns:
      `true` if the row was present, `false` otherwise

  - ### getSize

    public int getSize()
    Returns the size of the data set.
    Returns:
      the data set size

  - ### loadData

    protected List<String> loadData(File file, String encoding) throws IOException, FileNotFoundException
    Loads the data lines from the given file into a list.
    Parameters:
      `file` - the data file to load
      `encoding` - the data file encoding
    Returns:
      a list with the data lines
    Throws:
      `FileNotFoundException` - if the data file cannot be found
      `IOException` - if the data file cannot be opened or read

  - ### processLines

    protected List<String> processLines(List<String> lines)
    Post-processes the data lines just read. This method is responsible for comment line processing.
    Parameters:
      `lines` - the data lines
    Returns:
      the processed data lines