Package com.xceptance.xlt.api.data

Class DataProvider

  • public class DataProvider
extends java.lang.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 "[testsuite]/config/data" 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 java.lang.String DEFAULT
      Languages supported.
      static java.lang.String DEFAULT_FILE_ENCODING
      The default file encoding ("UTF-8").
      static java.lang.String DEFAULT_LINE_COMMENT_MARKER
      The default line comment character ("#").

    • Constructor Summary

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

    • Method Summary

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

      • DEFAULT

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

      • DEFAULT_FILE_ENCODING

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

      • DEFAULT_LINE_COMMENT_MARKER

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

    • Constructor Detail

      • DataProvider

        public DataProvider​(java.lang.String fileName)
             throws java.io.IOException,
                    java.io.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:
        java.io.FileNotFoundException - if the data file cannot be found
        java.io.IOException - if the data file cannot be opened or read

      • DataProvider

        public DataProvider​(java.lang.String fileName,
                    java.lang.String encoding)
             throws java.io.IOException,
                    java.io.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:
        java.io.FileNotFoundException - if the data file cannot be found
        java.io.IOException - if the data file cannot be opened or read

      • DataProvider

        public DataProvider​(java.lang.String fileName,
                    java.lang.String encoding,
                    java.lang.String lineCommentMarker)
             throws java.io.IOException,
                    java.io.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:
        java.io.FileNotFoundException - if the data file cannot be found
        java.io.IOException - if the data file cannot be opened or read

    • Method Detail

      • getInstance

        public static DataProvider getInstance​(java.lang.String fileName)
                                throws java.io.FileNotFoundException,
                                       java.io.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:
        java.io.FileNotFoundException - if the data file cannot be found
        java.io.IOException - if the data file cannot be opened or read

      • getAllRows

        public java.util.List<java.lang.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 java.lang.String getRandomRow()
        Returns a randomly-chosen data row.
        Returns:
        a row, or null if the data set is empty

      • getRandomRow

        public java.lang.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 java.lang.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 java.lang.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,
                   java.lang.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​(java.lang.String row)
        Adds a new data row as the last element to the internal store.
        Parameters:
        row - the new row

      • removeRow

        public java.lang.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​(java.lang.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 java.util.List<java.lang.String> loadData​(java.io.File file,
                                                    java.lang.String encoding)
                                             throws java.io.IOException,
                                                    java.io.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:
        java.io.FileNotFoundException - if the data file cannot be found
        java.io.IOException - if the data file cannot be opened or read

      • processLines

        protected java.util.List<java.lang.String> processLines​(java.util.List<java.lang.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