com.docmosis.template.population
Class DataProviderBuilder

java.lang.Object
  com.docmosis.template.population.DataProviderBuilder

public class DataProviderBuilder

extends Object

This class helps to collect the data together for insertion into a document. Data can be added from a variety of sources such as key value pairs, files, Java Objects and SQL ResultSets. The usage pattern is as follows:

   DataProviderBuilder dpb = new DataProviderBuilder();
   dpb.add(...);
   dpb.add(...);
   dpb.add(...);
   ...
   
   // use the data for a render
   DocumentProcessor.renderDoc(...., dpb.getDataProvider(), ...);
 

When populating templates, the structure of the data needs to match the structure of the template. This is the case no matter the source of data (Java, Strings, SQL etc). Look to the Docmosis Developer Guide for more information about lining up data and templates. Some specific notes about how this is achieved when adding Strings to the data follows. When adding Strings and files of delimited Strings, a "dot" notation is used to indicate a level of nesting in the data. For example

   dpb.add("hotel.floor.room", "101");
 

Corresponds to a structure:

    hotel
      floor
         room = "101"
 

meaning that hotel "contains" floor which "contains" room with a value of "101.

The following rules apply to String data being added:

1. Keys may contain numbers to order data eg "hotel.0.floor", "hotel.1.floor"...
2. Key numbering starts at 0 (zero) must increment without gaps
3. Keys may not start with a number. e.g. 0.hotel.2 is not valid.
4. Keys may not have two consecutive numbers. e.g. hotel.1.2.floor.2 is not valid.
5. A value of "[image:./abc.jpg]" indicates an image file adds the image to the data from the indicated file. If an StringInterceptor has been set for this class, it will be asked to interpret strings being added to allow special processing logic.

With Java objects, the nesting (or hierarchy) of information is given directly by the Java Objects themselves. With SQL Data, the data is simply a two dimensional grid of data unless a "grouping" definition is provided. The "grouping" definition allows the two dimensional grid of data to be transformed into a nesting (hierarchy) of information. See the javadoc on the specific methods for more information. It can create hierarchical data using a simple nested notation.

The period (".") character is used to spilt the keys into nesting levels. So the key "hotel.floor" indicates a sub-DataProvider named "hotel" contains a String value for "floor". Nesting may be done to an arbitrarty level and indexing may be used to set values at specific indexes. When data is added as key-value pairs some extra checks performed to create special forms of data from Strings. For example, a value "[image:abc.jpg]" is used to create an entry in the data which is the image stream loaded from the file abc.jpg. See the add(String, String) method for more information.

 Typical examples of use are:
 1. Create a data provider from simple delimited strings
         DataProviderBuilder dpb = new DataProviderBuilder();
         dpb.add("name", "Me Mo");
         dpb.add("age", "101");
         ...

 2. Add some nested data to an existing data set.  This example will
 create a nested structure of subjects containing details about subjects
 results:
         DataProviderBuilder dpb = new DataProviderBuilder();
         dpb.add("Report Title", "Student Subject Breakdown");
         dpb.addAll(new String[][]{
         {"subject.0.name", "English"},
         {"subject.0.comment", ""},
         {"subject.0.teacher", "J. Test"},
         {"subject.0.outcomes.0.outcome", "Listening and Speaking"},
         {"subject.0.outcomes.0.passed", "Y"},
         {"subject.0.outcomes.1.outcome", "Reading"},
         {"subject.0.outcomes.1.passed", "Y"},
         {"subject.0.outcomes.2.outcome", "Viewing"},
         {"subject.0.outcomes.2.passed", "Y"},
         {"subject.0.outcomes.3.outcome", "Writing"},
         {"subject.0.outcomes.3.passed", "N"},
        
         {"subject.1.name", "Mathematics"},
         {"subject.1.comment", ""},
         {"subject.1.teacher", "P. Test"},
         {"subject.1.outcomes.0.outcome", "Algebra"},
         {"subject.0.outcomes.0.passed", "Y"},
         {"subject.1.outcomes.1.outcome", "Chance and Data"},
         {"subject.0.outcomes.1.passed", "Y"},
         {"subject.1.outcomes.2.outcome", "Measurement"},
         {"subject.0.outcomes.2.passed", "Y"},
         {"subject.1.outcomes.3.outcome", "Number"},
         {"subject.0.outcomes.3.passed", "Y"},
         {"subject.1.outcomes.4.outcome", "Space"},
         {"subject.0.outcomes.4.passed", "Y"}});
         ...
 

Constructor Summary

DataProviderBuilder()
Construct a new DataProviderBuilder

DataProviderBuilder(MutableDataProvider addTo)
Construct a new DataProvider Builder using the given MutableDataProvider as the starting point.

Method Summary

DataProviderBuilder	add(DataProvider dp, String key) Add the given data provider to our current data under the given key.
DataProviderBuilder	add(String[] keyValuePair) Add a key value pair to the memory data provider.
DataProviderBuilder	add(String key, String value) Add a new key-value pair to the current data.
DataProviderBuilder	addAll(Map map) Add all key value pairs from a map to the memory data provider.
DataProviderBuilder	addAll(String[][] keyValuePairs) Add all key value pairs to the memory data provider.
DataProviderBuilder	addFile(File keyValuePairFile) Add a key-value pair file that using a comma as a delimiter.
DataProviderBuilder	addFile(File keyValuePairFile, char delimiter) Add a key-value pair file using the given delimiter to distinguish key from value.
DataProviderBuilder	addFile(File keyValuePairFile, char delimiter, String charSetName) Add a key-value pair file using the given delimiter to distinguish key from value.
DataProviderBuilder	addImage(String key, File imageFile) Add the given image (in a file) to the current data.
DataProviderBuilder	addImage(String key, InputStream imageStream) Add the given image (in an InputStream) to the current data.
DataProviderBuilder	addJavaObject(Object o) Deprecated. in favour of addJavaObject(Object, String). See warning.
DataProviderBuilder	addJavaObject(Object o, String key) Add the given Java object to our current data so that it may be referenced by the given key.
DataProviderBuilder	addJavaObject(Object o, String key, boolean forgiving) Add the given Java object to our current data so that it may be referenced by the given key, specifying the forgiving behaviour (see below).
DataProviderBuilder	addJSONFile(File jsonFile) Add a JSON file to the existing data provider.
DataProviderBuilder	addJSONString(String jsonString) Add a JSON string to the existing data provider.
DataProviderBuilder	addSQL(ResultSet rs, DataProviderGrouping[] grouping) Add the given ResultSet to our data using the given grouping definition to transform the ResultSet grid into a hierarchy.
DataProviderBuilder	addSQL(ResultSet rs, String key) Add the given ResultSet to our data.
void	addStringInterceptor(StringInterceptor newInterceptor) Add a StringInterceptor to this builder.
DataProviderBuilder	addXMLDocument(Document xmlDocument) Add an XML document to the existing data provider.
DataProviderBuilder	addXMLDocument(Document xmlDocument, XMLNodeFilter filter, boolean includeRoot) Add an XML document to the existing data provider.
DataProviderBuilder	addXMLFile(File xmlFile) Add an XML file to the existing data provider.
DataProviderBuilder	addXMLFile(File xmlFile, boolean includeRoot) Add an XML file to the existing data provider.
DataProviderBuilder	addXMLFile(File xmlFile, XMLNodeFilter filter, boolean includeRoot) Add an XML file to the existing data provider applying the given filter to selectively exclude some of the XML content.
DataProviderBuilder	addXMLStream(InputStream source, XMLNodeFilter filter, boolean includeRoot) Add the given input stream to this data provider, optionally filtering out content using the given filter and optionally including the root node.
DataProviderBuilder	addXMLString(String xml) Add the given XML string to this data provider.
DataProviderBuilder	addXMLString(String xml, XMLNodeFilter filter) Add the given XML string to this data provider, optionally filtering out content using the given filter.
DataProviderBuilder	addXMLString(String xml, XMLNodeFilter filter, boolean includeRoot) Add the given XML string to this data provider, optionally filtering out content using the given filter and optionally including the root node.
DataProvider	getDataProvider() Get the data provider that has been built so far.
String	toString()

Methods inherited from class java.lang.Object

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

Constructor Detail

DataProviderBuilder

public DataProviderBuilder()

Construct a new DataProviderBuilder

DataProviderBuilder

public DataProviderBuilder(MutableDataProvider addTo)

Construct a new DataProvider Builder using the given MutableDataProvider as the starting point.

Parameters:

addTo - the starting point of data.

Method Detail

addStringInterceptor

public void addStringInterceptor(StringInterceptor newInterceptor)

Add a StringInterceptor to this builder. The interceptors will be given a chance to intervene during string addition, to decide to alter the way strings are used. This is mostly intended for internal use, to cater to where strings represent other items such as encoded images. See the add(String, String) method and the class documentation for details about the use of the StringInterceptor.

Parameters:

newInterceptor - an interceptor which may change interpretation of strings.

Throws:

IllegalArgumentException - if the interceptor is null

See Also:

add(String, String)

addXMLDocument

public DataProviderBuilder addXMLDocument(Document xmlDocument)
                                   throws DOMException

Add an XML document to the existing data provider. The root of the document becomes the top level of the data in this data provider and no filtering is done. Adding XML recurses the entire XML tree unless a filter is supplied to one of the addXML* methods to exclude parts of the tree. Attributes of nodes are added as key/value pairs and node names are used as the key for deeper access into the data structure.

Parameters:

xmlDocument - the XML document containing the data to add to the data provider.

Returns:

this data provider builder

Throws:

DOMException - if the root node is missing from the document.

addXMLDocument

public DataProviderBuilder addXMLDocument(Document xmlDocument,
                                          XMLNodeFilter filter,
                                          boolean includeRoot)
                                   throws DOMException

Add an XML document to the existing data provider. If the filter supplied is not null, it will be given the chance to exclude parts of the XML structure from being added to this data provider builder. The root node is optionally included as the root of the data. Adding XML recurses the entire XML tree unless a filter is supplied to one of the addXML* methods to exclude parts of the tree. Attributes of nodes are added as key/value pairs and node names are used as the key for deeper access into the data structure.

Parameters:

xmlDocument - the XML document containing the data to add to the data provider.

filter - an XML filter to only allow nodes of interest. May be null.

includeRoot - if true the root node of the XML will form the root of the created data. Otherwise the data is build starting with the children of the root node.

Returns:

this data provider builder

Throws:

DOMException - if the root node is missing from the document.

addXMLFile

public DataProviderBuilder addXMLFile(File xmlFile)
                               throws IOException,
                                      SAXException,
                                      ParserConfigurationException,
                                      DOMException

Add an XML file to the existing data provider. Adding XML recurses the entire XML tree unless a filter is supplied to one of the addXML* methods to exclude parts of the tree. Attributes of nodes are added as key/value pairs and node names are used as the key for deeper access into the data structure.

Parameters:

xmlFile - the XML file containing the data to add to the data provider.

Returns:

this data provider builder

Throws:

DOMException - if the root node is missing from the document.

IOException

SAXException

ParserConfigurationException

addXMLFile

public DataProviderBuilder addXMLFile(File xmlFile,
                                      boolean includeRoot)
                               throws IOException,
                                      SAXException,
                                      ParserConfigurationException,
                                      DOMException

Add an XML file to the existing data provider. Adding XML recurses the entire XML tree unless a filter is supplied to one of the addXML* methods to exclude parts of the tree. Attributes of nodes are added as key/value pairs and node names are used as the key for deeper access into the data structure.

Parameters:

xmlFile - the XML file containing the data to add to the data provider.

includeRoot - if true the root node of the XML will form the root of the created data. Otherwise the data is build starting with the children of the root node.

Returns:

this data provider builder

Throws:

DOMException - if the root node is missing from the document.

IOException

SAXException

ParserConfigurationException

addXMLFile

public DataProviderBuilder addXMLFile(File xmlFile,
                                      XMLNodeFilter filter,
                                      boolean includeRoot)
                               throws IOException,
                                      SAXException,
                                      ParserConfigurationException,
                                      DOMException

Add an XML file to the existing data provider applying the given filter to selectively exclude some of the XML content. The root node of the XML forms the root of the data in this provider. Adding XML recurses the entire XML tree unless a filter is supplied to one of the addXML* methods to exclude parts of the tree. Attributes of nodes are added as key/value pairs and node names are used as the key for deeper access into the data structure.

Parameters:

xmlFile - the XML file containing the data to add to the data provider.

filter - an XML filter to only allow nodes of interest. May be null.

includeRoot - if true the root node of the XML will form the root of the created data. Otherwise the data is build starting with the children of the root node.

Returns:

this data provider builder

Throws:

DOMException - if the root node is missing from the document.

IOException

SAXException

ParserConfigurationException

addXMLString

public DataProviderBuilder addXMLString(String xml)
                                 throws ParserConfigurationException,
                                        SAXException,
                                        IOException

Add the given XML string to this data provider. Adding XML recurses the entire XML tree unless a filter is supplied to one of the addXML* methods to exclude parts of the tree. Attributes of nodes are added as key/value pairs and node names are used as the key for deeper access into the data structure.

Parameters:

xml - the XML text containing the data to add

Returns:

this instance

Throws:

ParserConfigurationException - if there is a problem preparing XML parsing

SAXException - if there is a problem with the XML

IOException - if an IO problem occurs

addXMLString

public DataProviderBuilder addXMLString(String xml,
                                        XMLNodeFilter filter)
                                 throws ParserConfigurationException,
                                        SAXException,
                                        IOException

Add the given XML string to this data provider, optionally filtering out content using the given filter. Adding XML recurses the entire XML tree unless a filter is supplied to one of the addXML* methods to exclude parts of the tree. Attributes of nodes are added as key/value pairs and node names are used as the key for deeper access into the data structure.

Parameters:

xml - the XML text containing the data to add

filter - a filter (or null) that can be used to stop content from the given XML being included in the data.

Returns:

this instance

Throws:

ParserConfigurationException - if there is a problem preparing XML parsing

SAXException - if there is a problem with the XML

IOException - if an IO problem occurs

addXMLString

public DataProviderBuilder addXMLString(String xml,
                                        XMLNodeFilter filter,
                                        boolean includeRoot)
                                 throws ParserConfigurationException,
                                        SAXException,
                                        IOException

Add the given XML string to this data provider, optionally filtering out content using the given filter and optionally including the root node. Adding XML recurses the entire XML tree unless a filter is supplied to one of the addXML* methods to exclude parts of the tree. Attributes of nodes are added as key/value pairs and node names are used as the key for deeper access into the data structure.

Parameters:

xml - the XML text containing the data to add

filter - a filter (or null) that can be used to stop content from the given XML being included in the data.

includeRoot - if true the root node of the XML will form the root of the created data. Otherwise the data is build starting with the children of the root node.

Returns:

this instance

Throws:

ParserConfigurationException - if there is a problem preparing XML parsing

SAXException - if there is a problem with the XML

IOException - if an IO problem occurs

addXMLStream

public DataProviderBuilder addXMLStream(InputStream source,
                                        XMLNodeFilter filter,
                                        boolean includeRoot)
                                 throws ParserConfigurationException,
                                        SAXException,
                                        IOException

Add the given input stream to this data provider, optionally filtering out content using the given filter and optionally including the root node. Adding XML recurses the entire XML tree unless a filter is supplied to one of the addXML* methods to exclude parts of the tree. Attributes of nodes are added as key/value pairs and node names are used as the key for deeper access into the data structure.

Parameters:

source - the input stream over the XML data

filter - the filter to use to prune parts of the XML tree

includeRoot - if true the root node of the XML will form the root of the created data. Otherwise the data is build starting with the children of the root node.

Returns:

this instance

Throws:

ParserConfigurationException - if there is a problem preparing XML parsing

SAXException - if there is a problem with the XML

IOException - if an IO problem occurs

addJSONString

public DataProviderBuilder addJSONString(String jsonString)
                                  throws JSONException

Add a JSON string to the existing data provider.

Returns:

a data provider builder containing the resultant data provider.

Throws:

JSONException

addJSONFile

public DataProviderBuilder addJSONFile(File jsonFile)
                                throws IOException,
                                       JSONException

Add a JSON file to the existing data provider.

Parameters:

jsonFile - the JSON file containing the data to add to the data provider.

Returns:

a data provider builder containing the resultant data provider.

Throws:

IOException

JSONException

addJavaObject

public DataProviderBuilder addJavaObject(Object o)

Deprecated. in favour of addJavaObject(Object, String). See warning.

Add a Java object to the "top level" of our data (see Warnings). Being at the top level means that the template expects to be able to reference into the given object without having to "step" into the object or look it up first.

Warning: This method should only be used when no other add methods are being called on this instance since it is easy for a Java object added by this method to mask other data. The addJavaObject(Object, String) is far safer for general use.

For example, given:

   DataProviderBuilder dpb = new DataProviderBuilder();
   dpb.addJavaObject(person);
 

the template would reference the first name directly. So the field in the template could be "getFirstName()".

NOTE: if the docmosis property "docmosis.populator.lookup.java.forgiving" is set to false then lookups to Java objects where the method can't be found produces an error. By default this is set to true.

Parameters:

o - the Java object to add to the root of our data

Returns:

this builder

addJavaObject

public DataProviderBuilder addJavaObject(Object o,
                                         String key)

Add the given Java object to our current data so that it may be referenced by the given key.

NOTE: key nesting is not supported for this method (see the documentation at the top of this class about nesting). For example, given:

   DataProviderBuilder dpb = new DataProviderBuilder();
   dpb.addJavaObject(person, "myPerson");
 

the template would reference the first name in the context of the key "person". So the field in the template could be "myPerson.getFirstName()".

NOTE: if the docmosis property "docmosis.populator.lookup.java.forgiving" is set to false then lookups to Java objects where the method can't be found produces an error. By default this is set to true and a lookup on a non-existent Java method is the same as if there is no data.

Parameters:

o - the object to add

key - the key under which the object will be referenced

Returns:

this builder

addJavaObject

public DataProviderBuilder addJavaObject(Object o,
                                         String key,
                                         boolean forgiving)

Add the given Java object to our current data so that it may be referenced by the given key, specifying the forgiving behaviour (see below).

NOTE: key nesting is not supported for this method (see the documentation at the top of this class about nesting). For example, given:

   DataProviderBuilder dpb = new DataProviderBuilder();
   dpb.addJavaObject(person, "myPerson");
 

the template would reference the first name in the context of the key "person". So the field in the template could be "myPerson.getFirstName()".

NOTE: if the docmosis property "docmosis.populator.lookup.java.forgiving" is set to false then lookups to Java objects where the method can't be found produces an error. By default this is set to true and a lookup on a non-existent Java method is the same as if there is no data. The forgiving parameter overrides the properties that are set.

Parameters:

o - the object to add

key - the key under which the object will be referenced

forgiving - whether attempts to reference a non-existent method on the Java Objects are fatal or ignored. Overrides default property settings.

Returns:

this builder

addSQL

public DataProviderBuilder addSQL(ResultSet rs,
                                  String key)
                           throws SQLException

Add the given ResultSet to our data. Each row of the ResultSet is added against the given key in an indexed fashion. Further, each column in the row is referenced by the name of the corresponding column in the query. The column names are extracted from the ResultSetMetaData.

For example, data setup like this:

   ResultSet myResultSet = executeQuery("select number, rooms from floors where hotelid = 1");
   dpb.addSQL(myResultSet, "floors");
 

could be referenced in the template using fields named:

   "floors[0].number" 
   or
   "floors[1].rooms"
 

NOTE: All data is read into memory from the resultset.

Parameters:

rs - the result set containing the results of a database query

key - the key under which the data will be referenced.

Returns:

this builder

Throws:

SQLException - if an SQLException occurs during reading of the data

addSQL

public DataProviderBuilder addSQL(ResultSet rs,
                                  DataProviderGrouping[] grouping)
                           throws NoSuchColumnNameException,
                                  SQLException,
                                  DataProviderGroupingException

Add the given ResultSet to our data using the given grouping definition to transform the ResultSet grid into a hierarchy.

Parameters:

rs - the result set containing the results of a database query

grouping - the grouping definition for transforming data into a hierarchy

Returns:

this builder

Throws:

SQLException - if something goes wrong reading from the result set.

DataProviderGroupingException - if there is a problem with grouping the data.

NoSuchColumnNameException - for invalid column names in the groupings.

add

public DataProviderBuilder add(DataProvider dp,
                               String key)

Add the given data provider to our current data under the given key.

Parameters:

dp - the DataProvider to add

key - the key under which to add the given data provider

Returns:

this builder

addImage

public DataProviderBuilder addImage(String key,
                                    File imageFile)

Add the given image (in a file) to the current data. The key may be nested (see the documentation at the top of this class about nesting).

Parameters:

imageFile - the file containing the image

key - the key under which the image will be referenced

Returns:

this builder

Throws:

IllegalArgumentException - if the key is not valid (ie starts with a number or contains an out-of-sequence index)

addImage

public DataProviderBuilder addImage(String key,
                                    InputStream imageStream)

Add the given image (in an InputStream) to the current data. The key may be nested (see the documentation at the top of this class about nesting).

Parameters:

imageStream - the InputStream containing the image

key - the key under which the image will be referenced

Returns:

this builder

Throws:

IllegalArgumentException - if the key is not valid (ie starts with a number or contains an out-of-sequence index).

add

public DataProviderBuilder add(String key,
                               String value)

Add a new key-value pair to the current data. The key may be nested (see the documentation at the top of this class about nesting).

 The following VALUEs are treated specially:
   true   - data is added as a Boolean TRUE value
   false  - data is added as a Boolean FALSE value
   [image:xxx.jpg] - xxx.jpg is assumed to be
            a file that specifies the image.
 

Also, if any StringInterceptors have been added, they will be called and given the chance to apply special interpretations to the key and value.

Parameters:

key - a for the element.

value - the value to pass in.

Returns:

this builder

Throws:

IllegalArgumentException - if the key is not valid (ie starts with a number or contains an out-of-sequence index).

add

public DataProviderBuilder add(String[] keyValuePair)

Add a key value pair to the memory data provider. This is equivalent to the add(String, String) method and the same special interpretation of the keys and values applies.

Parameters:

keyValuePair - an array of length two, where the first element is the key and the second element is the value.

Returns:

the resulting data provider adapter.

See Also:

add(String, String)

addAll

public DataProviderBuilder addAll(String[][] keyValuePairs)

Add all key value pairs to the memory data provider. This method is equivalent to adding all key-value pairs from the array using the add(String, String) method. The same special interpretation to the keys and values applies.

Parameters:

keyValuePairs - an double array of width two, and any height. For the width, each first element is the key and second element is the value. For the height, each element corresponds to another key value pair.

Returns:

the resulting data provider adapter.

See Also:

add(String, String)

addAll

public DataProviderBuilder addAll(Map map)

Add all key value pairs from a map to the memory data provider. It is assumed that all keys and values are String objects. If you want to add a Java Map that is not a key-value pair of strings then use the addJavaObject() methods. This method is equivalent to adding all key-value pairs from the Map using the add(String, String) method. The same special interpretation to the keys and values applies.

Parameters:

map - the map to get the key value pairs from.

Returns:

this builder.

See Also:

addJavaObject(Object), add(String, String)

addFile

public DataProviderBuilder addFile(File keyValuePairFile)
                            throws IOException

Add a key-value pair file that using a comma as a delimiter. The key value pairs in the file can also reference images etc using the special notation that applies to String values described in the Java Doc for this class. This method is equivalent to adding all key-value pairs from the file using the add(String, String) method. The same special interpretation to the values applies. This means, for example, the file can reference image files to include as images. The default character encoding for the platform is used (see java.io.InputStreamReader).

Parameters:

keyValuePairFile - a file containing key value pairs, with two values separated by the default delimiter. Each line represents another key value pair. Within each row, the first element is the key and the second element is the value.

Returns:

this builder

Throws:

UnsupportedEncodingException - if the give charSetName is not valid

IOException - if there's a problem reading from the file.

See Also:

add(String, String)

addFile

public DataProviderBuilder addFile(File keyValuePairFile,
                                   char delimiter)
                            throws IOException

Add a key-value pair file using the given delimiter to distinguish key from value. The key value pairs in the file can also reference images etc using the special notation that applies to String values described in the Java Doc for this class. This method is equivalent to adding all key-value pairs from the file using the add(String, String) method. The same special interpretation to the values applies. This means, for example, the file can reference image files to include as images. The default character encoding for the platform is used (see java.io.InputStreamReader).

Parameters:

keyValuePairFile - a file containing key value pairs, with two values separated by a given delimiter. Each row represents another key value pair. Within each line, the first element is the key and the second element is the value.

delimiter - the delimiter to separate each key from the value.

Returns:

this builder

Throws:

UnsupportedEncodingException - if the give charSetName is not valid

IOException - if there's a problem reading from the file.

See Also:

add(String, String)

addFile

public DataProviderBuilder addFile(File keyValuePairFile,
                                   char delimiter,
                                   String charSetName)
                            throws IOException

Add a key-value pair file using the given delimiter to distinguish key from value. The key value pairs in the file can also reference images etc using the special notation that applies to String values described in the Java Doc for this class. This method is equivalent to adding all key-value pairs from the file using the add(String, String) method. The same special interpretation to the values applies. This means, for example, the file can reference image files to include as images. The charSetName specifies a character encoding to use when reading the file (eg "UTF-8" - see java.nio.charset.Charset). If the given charSetName is null, the default character encoding is used for the platform (see java.io.InputStreamReader)

Parameters:

keyValuePairFile - a file containing key value pairs, with two values separated by a given delimiter. Each row represents another key value pair. Within each line, the first element is the key and the second element is the value.

delimiter - the delimiter to separate each key from the value.

charSetName - The name of a supported charset. A null value means the platform default character encoding will be used.

Returns:

this builder

Throws:

UnsupportedEncodingException - if the give charSetName is not valid

IOException - if there's a problem reading from the file.

See Also:

add(String, String)

getDataProvider

public DataProvider getDataProvider()

Get the data provider that has been built so far. The underlying data provider will vary depending on how data is constructed so callers should not generally infer anything about the implementation returned other that that mandated by the DataProvider implementation.

Returns:

null if no data has been added.

toString

public String toString()