package io.ebean.text.csv;

import io.ebean.text.StringParser;

import java.io.Reader;
import java.util.Locale;

Reads CSV data turning it into object graphs that you can be saved (inserted)
or processed yourself.
 This first example doesn't use a CsvCallback and this means it will automatically create a transaction, save the customers and commit the transaction when successful. 

try {
  File f = new File("src/test/resources/test1.csv");
  FileReader reader = new FileReader(f);
  CsvReader<Customer> csvReader = DB.createCsvReader(Customer.class);
  csvReader.setPersistBatchSize(20);
  csvReader.addProperty("status");
  // ignore the next property
  csvReader.addIgnore();
  csvReader.addProperty("name");
  csvReader.addDateTime("anniversary", "dd-MMM-yyyy");
  csvReader.addProperty("billingAddress.line1");
  csvReader.addProperty("billingAddress.city");
  csvReader.process(reader);
 } catch (Exception e) {
  throw new RuntimeException(e);
 }

Type parameters:
<T> – the entity bean type/**
 * Reads CSV data turning it into object graphs that you can be saved (inserted)
 * or processed yourself.
 * <p>
 * This first example doesn't use a {@link CsvCallback} and this means it will
 * automatically create a transaction, save the customers and commit the
 * transaction when successful.
 * </p>
 *
 * <pre>{@code
 * try {
 *   File f = new File("src/test/resources/test1.csv");
 *
 *   FileReader reader = new FileReader(f);
 *
 *   CsvReader<Customer> csvReader = DB.createCsvReader(Customer.class);
 *
 *   csvReader.setPersistBatchSize(20);
 *
 *   csvReader.addProperty("status");
 *   // ignore the next property
 *   csvReader.addIgnore();
 *   csvReader.addProperty("name");
 *   csvReader.addDateTime("anniversary", "dd-MMM-yyyy");
 *   csvReader.addProperty("billingAddress.line1");
 *   csvReader.addProperty("billingAddress.city");
 *
 *   csvReader.process(reader);
 *
 * } catch (Exception e) {
 *   throw new RuntimeException(e);
 * }
 * }</pre>
 *
 * @param <T> the entity bean type
 */
public interface CsvReader<T> {

  
Explicitly set the default Locale.
/**
   * Explicitly set the default Locale.
   */
  void setDefaultLocale(Locale defaultLocale);

  
Set the default format to use for Time types.
/**
   * Set the default format to use for Time types.
   */
  void setDefaultTimeFormat(String defaultTimeFormat);

  
Set the default format to use for Date types.
/**
   * Set the default format to use for Date types.
   */
  void setDefaultDateFormat(String defaultDateFormat);

  
Set the default format to use for Timestamp types.
/**
   * Set the default format to use for Timestamp types.
   */
  void setDefaultTimestampFormat(String defaultTimestampFormat);

  
Set the batch size for using JDBC statement batching.

By default this is set to 20 and setting this to 1 will disable the use of
JDBC statement batching.

/**
   * Set the batch size for using JDBC statement batching.
   * <p>
   * By default this is set to 20 and setting this to 1 will disable the use of
   * JDBC statement batching.
   * </p>
   */
  void setPersistBatchSize(int persistBatchSize);

  
Set to true if there is a header row that should be ignored.

If addPropertiesFromHeader is true then all the properties are added using
the default time,date and timestamp formats.

If you have a mix of dateTime formats you can not use this method and must
add the properties yourself.

/**
   * Set to true if there is a header row that should be ignored.
   * <p>
   * If addPropertiesFromHeader is true then all the properties are added using
   * the default time,date and timestamp formats.
   * <p>
   * If you have a mix of dateTime formats you can not use this method and must
   * add the properties yourself.
   * </p>
   */
  void setHasHeader(boolean hasHeader, boolean addPropertiesFromHeader);

  
Same as setHasHeader(true,true);

This will use a header to define all the properties to load using the
default formats for time, date and datetime types.

/**
   * Same as setHasHeader(true,true);
   * <p>
   * This will use a header to define all the properties to load using the
   * default formats for time, date and datetime types.
   * </p>
   */
  void setAddPropertiesFromHeader();

  
Same as setHasHeader(true, false);

This indicates that there is a header but that it should be ignored.

/**
   * Same as setHasHeader(true, false);
   * <p>
   * This indicates that there is a header but that it should be ignored.
   * </p>
   */
  void setIgnoreHeader();

  
Set the frequency with which a INFO message will be logged showing the
progress of the processing. You might set this to 1000 or 10000 etc.

If this is not set then no INFO messages will be logged.

/**
   * Set the frequency with which a INFO message will be logged showing the
   * progress of the processing. You might set this to 1000 or 10000 etc.
   * <p>
   * If this is not set then no INFO messages will be logged.
   * </p>
   */
  void setLogInfoFrequency(int logInfoFrequency);

  
Ignore the next column of data.
/**
   * Ignore the next column of data.
   */
  void addIgnore();

  
Define the property which will be loaded from the next column of data.

This takes into account the data type of the property and handles the
String to object conversion automatically.

/**
   * Define the property which will be loaded from the next column of data.
   * <p>
   * This takes into account the data type of the property and handles the
   * String to object conversion automatically.
   * </p>
   */
  void addProperty(String propertyName);

  
Define the next property and use a custom StringParser to convert the
string content into the appropriate type for the property.
/**
   * Define the next property and use a custom StringParser to convert the
   * string content into the appropriate type for the property.
   */
  void addProperty(String propertyName, StringParser parser);

  
Add a property with a custom Date/Time/Timestamp format using the default
Locale. This will convert the string into the appropriate java type for the
given property (Date, Calendar, SQL Date, Time, Timestamp, JODA etc).
/**
   * Add a property with a custom Date/Time/Timestamp format using the default
   * Locale. This will convert the string into the appropriate java type for the
   * given property (Date, Calendar, SQL Date, Time, Timestamp, JODA etc).
   */
  void addDateTime(String propertyName, String dateTimeFormat);

  
Add a property with a custom Date/Time/Timestamp format. This will convert
the string into the appropriate java type for the given property (Date,
Calendar, SQL Date, Time, Timestamp, JODA etc).
/**
   * Add a property with a custom Date/Time/Timestamp format. This will convert
   * the string into the appropriate java type for the given property (Date,
   * Calendar, SQL Date, Time, Timestamp, JODA etc).
   */
  void addDateTime(String propertyName, String dateTimeFormat, Locale locale);

  
Automatically create a transaction if required to process all the CSV
content from the reader.

This will check for a current transaction. If there is no current
transaction then one is started and will commit (or rollback) at the end of
processing. This will also set the persistBatchSize on the transaction.

/**
   * Automatically create a transaction if required to process all the CSV
   * content from the reader.
   * <p>
   * This will check for a current transaction. If there is no current
   * transaction then one is started and will commit (or rollback) at the end of
   * processing. This will also set the persistBatchSize on the transaction.
   * </p>
   */
  void process(Reader reader) throws Exception;

  
Process the CSV content passing the bean to the CsvCallback after each row.

This provides you with the ability to modify and process the bean.


When using a CsvCallback the reader WILL NOT create a transaction or save
the bean(s) for you. If you want to insert the processed beans you must
create your own transaction and save the bean(s) yourself.

/**
   * Process the CSV content passing the bean to the CsvCallback after each row.
   * <p>
   * This provides you with the ability to modify and process the bean.
   * </p>
   * <p>
   * When using a CsvCallback the reader WILL NOT create a transaction or save
   * the bean(s) for you. If you want to insert the processed beans you must
   * create your own transaction and save the bean(s) yourself.
   * </p>
   */
  void process(Reader reader, CsvCallback<T> callback) throws Exception;

}