Package com.xceptance.xlt.api.data

# Class ExclusiveDataProvider<T>

java.lang.Object
com.xceptance.xlt.api.data.ExclusiveDataProvider<T>

Type Parameters:
  `T` - type of managed data

public class ExclusiveDataProvider<T> extends Object
Provides exclusive data access. The given file is partitioned so that every agent has an exclusive set of lines. These lines get parsed into the dates to manage by this provider.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `ExclusiveDataProvider.Parser<T>`
  Implement this parser to use parsed

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final ExclusiveDataProvider.Parser<String>`
  `DEFAULT_PARSER`
  Parser that just returns the received lines.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ExclusiveDataProvider(String fileName, boolean filterLineComments, ExclusiveDataProvider.Parser<T> parser)`
  Creates a new `ExclusiveDataProvider` instance and initializes it with the agent's exclusive data partition loaded from the given data file.
  `ExclusiveDataProvider(String fileName, ExclusiveDataProvider.Parser<T> parser)`
  Creates a new `ExclusiveDataProvider` instance and initializes it with the agent's exclusive data partition loaded from the given data file.
  `ExclusiveDataProvider(String fileName, String encoding, boolean filterLineComments, ExclusiveDataProvider.Parser<T> parser)`
  Creates a new `ExclusiveDataProvider` instance and initializes it with the agent's exclusive data partition loaded from the given data file.
  `ExclusiveDataProvider(String fileName, String encoding, ExclusiveDataProvider.Parser<T> parser)`
  Creates a new `ExclusiveDataProvider` instance and initializes it with the agent's exclusive data partition loaded from the given data file.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `add(T item)`
  Add a new or release a previously received exclusive item.
  `T`
  `get()`
  Allocate the next available item for exclusive use.
  `static ExclusiveDataProvider.Parser<String>`
  `getDefaultParser()`
  Default parser that just returns the lines it receives.
  `static ExclusiveDataProvider<String>`
  `getInstance(String fileName)`
  Returns the exclusive data provider responsible for the given file name.
  `static ExclusiveDataProvider<String>`
  `getInstance(String fileName, boolean filterLineComments)`
  Returns the exclusive data provider responsible for the given file name.
  `static <T> ExclusiveDataProvider<T>`
  `getInstance(String fileName, boolean filterLineComments, ExclusiveDataProvider.Parser<T> parser)`
  Returns the exclusive data provider responsible for the given file name.
  `static <T> ExclusiveDataProvider<T>`
  `getInstance(String fileName, ExclusiveDataProvider.Parser<T> parser)`
  Returns the exclusive data provider responsible for the given file name.
  `static ExclusiveDataProvider<String>`
  `getInstance(String fileName, String encoding)`
  Returns the exclusive data provider responsible for the given file name.
  `static <T> ExclusiveDataProvider<T>`
  `getInstance(String fileName, String encoding, boolean filterLineComments, ExclusiveDataProvider.Parser<T> parser)`
  Returns the exclusive data provider responsible for the given file name.
  `static <T> ExclusiveDataProvider<T>`
  `getInstance(String fileName, String encoding, ExclusiveDataProvider.Parser<T> parser)`
  Returns the exclusive data provider responsible for the given file name.
  `static ExclusiveDataProvider<String>`
  `getNewInstance(String fileName)`
  Creates a new `ExclusiveDataProvider` instance for String data and initializes it with the agent's exclusive data partition loaded from the given data file.
  `static ExclusiveDataProvider<String>`
  `getNewInstance(String fileName, String encoding)`
  Creates a new `ExclusiveDataProvider` instance for String data and initializes it with the agent's exclusive data partition loaded from the given data file.
  `T`
  `getRandom()`
  Allocate a random item for exclusive use.
  `protected static <T> List<T>`
  `loadData(String fileName, String encoding, boolean filterLineComments, ExclusiveDataProvider.Parser<T> parser)`
  Get the agent's exclusive data partition loaded from the given data file and parse this partition using the given parser.
  `protected static <T> List<T>`
  `loadData(String fileName, String encoding, ExclusiveDataProvider.Parser<T> parser)`
  Get the agent's exclusive data partition loaded from the given data file and parse this partition using the given parser.
  `protected static <T> List<T>`
  `parse(List<String> lines, ExclusiveDataProvider.Parser<T> parser)`
  Parse the given lines and return the resulting data objects.
  `int`
  `size()`
  Get the number of available items.

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

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

- ## Field Details

  - ### DEFAULT_PARSER

    public static final ExclusiveDataProvider.Parser<String> DEFAULT_PARSER
    Parser that just returns the received lines.

- ## Constructor Details

  - ### ExclusiveDataProvider

    public ExclusiveDataProvider(String fileName, boolean filterLineComments, ExclusiveDataProvider.Parser<T> parser) throws FileNotFoundException, IOException
    Creates a new `ExclusiveDataProvider` instance and initializes it with the agent's exclusive data partition loaded from the given data file. The data file is expected to be saved using `DataProvider.DEFAULT_FILE_ENCODING`.
    Parameters:
      `fileName` - the name/path of the data file
      `filterLineComments` - whether line comments in given file should be automatically filtered out before content is handed over to given parser
      `parser` - parser to parse the content of the given file with
    Throws:
      `FileNotFoundException` - if the data file cannot be found
      `IOException` - if the data file cannot be opened or read
    See Also:
      - `DataProvider.DEFAULT_LINE_COMMENT_MARKER`

  - ### ExclusiveDataProvider

    public ExclusiveDataProvider(String fileName, ExclusiveDataProvider.Parser<T> parser) throws FileNotFoundException, IOException
    Creates a new `ExclusiveDataProvider` instance and initializes it with the agent's exclusive data partition loaded from the given data file. The data file is expected to be saved using `DataProvider.DEFAULT_FILE_ENCODING`.

    Line comments won't be automatically filtered out and need to be handled by the given parser.

    Parameters:
      `fileName` - the name/path of the data file
      `parser` - parser to parse the content of given file with
    Throws:
      `FileNotFoundException` - if the data file cannot be found
      `IOException` - if the data file cannot be opened or read
    See Also:
      - `DataProvider.DEFAULT_LINE_COMMENT_MARKER`

  - ### ExclusiveDataProvider

    public ExclusiveDataProvider(String fileName, String encoding, ExclusiveDataProvider.Parser<T> parser) throws FileNotFoundException, IOException
    Creates a new `ExclusiveDataProvider` instance and initializes it with the agent's exclusive data partition loaded from the given data file.

    Line comments won't be automatically filtered out and need to be handled by the given parser.

    Parameters:
      `fileName` - the name/path of the data file
      `encoding` - the file's encoding
      `parser` - parser to parse the content of given file with
    Throws:
      `FileNotFoundException` - if the data file cannot be found
      `IOException` - if the data file cannot be opened or read
    See Also:
      - `DataProvider.DEFAULT_LINE_COMMENT_MARKER`

  - ### ExclusiveDataProvider

    public ExclusiveDataProvider(String fileName, String encoding, boolean filterLineComments, ExclusiveDataProvider.Parser<T> parser) throws FileNotFoundException, IOException
    Creates a new `ExclusiveDataProvider` instance and initializes it with the agent's exclusive data partition loaded from the given data file.
    Parameters:
      `fileName` - the name/path of the data file
      `encoding` - the file's encoding
      `filterLineComments` - whether line comments in given file should be automatically filtered out before content is handed over to given parser
      `parser` - parser to parse the content of the given file with
    Throws:
      `FileNotFoundException` - if the data file cannot be found
      `IOException` - if the data file cannot be opened or read
    See Also:
      - `DataProvider.DEFAULT_LINE_COMMENT_MARKER`

- ## Method Details

  - ### getNewInstance

    public static ExclusiveDataProvider<String> getNewInstance(String fileName) throws FileNotFoundException, IOException
    Creates a new `ExclusiveDataProvider` instance for String data and initializes it with the agent's exclusive data partition loaded from the given data file. The data file is expected to be saved using `DataProvider.DEFAULT_FILE_ENCODING`.

    Line comments won't be handled in any way.

    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

  - ### getNewInstance

    public static ExclusiveDataProvider<String> getNewInstance(String fileName, String encoding) throws FileNotFoundException, IOException
    Creates a new `ExclusiveDataProvider` instance for String data and initializes it with the agent's exclusive data partition loaded from the given data file. The data file is expected to be saved using `DataProvider.DEFAULT_FILE_ENCODING`.

    Line comments won't be handled in any way.

    Parameters:
      `fileName` - the name/path of the data file
      `encoding` - the encoding the file was saved with
    Throws:
      `FileNotFoundException` - if the data file cannot be found
      `IOException` - if the data file cannot be opened or read

  - ### loadData

    protected static <T> List<T> loadData(String fileName, String encoding, boolean filterLineComments, ExclusiveDataProvider.Parser<T> parser) throws FileNotFoundException, IOException
    Get the agent's exclusive data partition loaded from the given data file and parse this partition using the given parser.
    Parameters:
      `fileName` - the name/path of the data file
      `encoding` - the file's encoding
      `filterLineComments` - whether line comments in given file should be automatically filtered out before content is handed over to given parser
      `parser` - parser to parse the content of the given file with
    Throws:
      `FileNotFoundException` - if the data file cannot be found
      `IOException` - if the data file cannot be opened or read
    See Also:
      - `DataProvider.DEFAULT_LINE_COMMENT_MARKER`

  - ### loadData

    protected static <T> List<T> loadData(String fileName, String encoding, ExclusiveDataProvider.Parser<T> parser) throws FileNotFoundException, IOException
    Get the agent's exclusive data partition loaded from the given data file and parse this partition using the given parser.

    Line comments won't be automatically filtered out and need to be handled by the given parser.

    Parameters:
      `fileName` - the name/path of the data file
      `encoding` - the file's encoding
      `parser` - parser to parse the content of the given file with
    Throws:
      `FileNotFoundException` - if the data file cannot be found
      `IOException` - if the data file cannot be opened or read
    See Also:
      - `DataProvider.DEFAULT_LINE_COMMENT_MARKER`

  - ### parse

    protected static <T> List<T> parse(List<String> lines, ExclusiveDataProvider.Parser<T> parser)
    Parse the given lines and return the resulting data objects.
    Parameters:
      `lines` - the lines to parse
      `parser` - parser to convert the read lines to the desired object

  - ### getInstance

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

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

    Line comments won't be handled in any way.

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

  - ### getInstance

    public static ExclusiveDataProvider<String> getInstance(String fileName, boolean filterLineComments) throws FileNotFoundException, IOException
    Returns the exclusive data provider responsible for the given file name. If an exclusive data provider has not been requested yet for this file name, then a new exclusive data provider is created, otherwise the previously created provider will be returned. Note that the exclusive data providers will be initialized using the default parser `getDefaultParser()`.

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

    Parameters:
      `fileName` - the file name/path of the data file
      `filterLineComments` - whether line comments in given file should be automatically filtered out before content is handed over to given parser
    Returns:
      the exclusive data provider
    Throws:
      `FileNotFoundException` - if the data file cannot be found
      `IOException` - if the data file cannot be opened or read

  - ### getInstance

    public static ExclusiveDataProvider<String> getInstance(String fileName, String encoding) throws FileNotFoundException, IOException
    Returns the exclusive data provider responsible for the given file name. If an exclusive data provider has not been requested yet for this file name, then a new exclusive data provider is created, otherwise the previously created provider will be returned. Note that the exclusive data providers will be initialized using the default parser `getDefaultParser()`.

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

    Line comments won't be handled in any way.

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

  - ### getInstance

    public static <T> ExclusiveDataProvider<T> getInstance(String fileName, String encoding, ExclusiveDataProvider.Parser<T> parser) throws FileNotFoundException, IOException
    Returns the exclusive data provider responsible for the given file name. If an exclusive data provider has not been requested yet for this file name, then a new exclusive data provider is created, otherwise the previously created provider will be returned.

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

    Line comments won't be automatically filtered out and need to be handled by the given parser.

    Parameters:
      `fileName` - the file name/path of the data file
      `encoding` - file encoding
      `parser` - parser to parse the lines with
    Returns:
      the exclusive data provider
    Throws:
      `FileNotFoundException` - if the data file cannot be found
      `IOException` - if the data file cannot be opened or read
    See Also:
      - `DataProvider.DEFAULT_LINE_COMMENT_MARKER`

  - ### getInstance

    public static <T> ExclusiveDataProvider<T> getInstance(String fileName, boolean filterLineComments, ExclusiveDataProvider.Parser<T> parser) throws FileNotFoundException, IOException
    Returns the exclusive data provider responsible for the given file name. If an exclusive data provider has not been requested yet for this file name, then a new exclusive data provider is created, otherwise the previously created provider will be returned. Note that the exclusive data providers will be initialized using `DataProvider.DEFAULT_FILE_ENCODING`.

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

    Parameters:
      `fileName` - the file name/path of the data file
      `filterLineComments` - whether line comments in given file should be automatically filtered out before content is handed over to given parser
      `parser` - parser to parse the lines with
    Returns:
      the exclusive data provider
    Throws:
      `FileNotFoundException` - if the data file cannot be found
      `IOException` - if the data file cannot be opened or read
    See Also:
      - `DataProvider.DEFAULT_LINE_COMMENT_MARKER`

  - ### getInstance

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

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

    Line comments won't be automatically filtered out and need to be handled by the given parser.

    Parameters:
      `fileName` - the file name/path of the data file
      `parser` - parser to parse the lines with
    Returns:
      the exclusive data provider
    Throws:
      `FileNotFoundException` - if the data file cannot be found
      `IOException` - if the data file cannot be opened or read
    See Also:
      - `DataProvider.DEFAULT_LINE_COMMENT_MARKER`

  - ### getInstance

    public static <T> ExclusiveDataProvider<T> getInstance(String fileName, String encoding, boolean filterLineComments, ExclusiveDataProvider.Parser<T> parser) throws FileNotFoundException, IOException
    Returns the exclusive data provider responsible for the given file name. If an exclusive data provider has not been requested yet for this file name, then a new exclusive data provider is created, otherwise the previously created provider will be returned.

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

    Parameters:
      `fileName` - the file name/path of the data file
      `encoding` - file encoding
      `filterLineComments` - whether line comments in given file should be automatically filtered out before content is handed over to given parser
      `parser` - parser to parse the lines with
    Returns:
      the exclusive data provider
    Throws:
      `FileNotFoundException` - if the data file cannot be found
      `IOException` - if the data file cannot be opened or read
    See Also:
      - `DataProvider.DEFAULT_LINE_COMMENT_MARKER`

  - ### get

    public T get()
    Allocate the next available item for exclusive use.
    Returns:
      the first item or `null` if no item is available

  - ### getRandom

    public T getRandom()
    Allocate a random item for exclusive use.
    Returns:
      a random item or `null` if no item is available

  - ### add

    public void add(T item)
    Add a new or release a previously received exclusive item.
    Parameters:
      `item` - the item to add

  - ### size

    public int size()
    Get the number of available items.
    Returns:
      number of available items

  - ### getDefaultParser

    public static ExclusiveDataProvider.Parser<String> getDefaultParser()
    Default parser that just returns the lines it receives.
    Returns:
      list of lines