001package io.ebean.text.csv;
002
003import io.ebean.text.StringParser;
004
005import java.io.Reader;
006import java.util.Locale;
007
008/**
009 * Reads CSV data turning it into object graphs that you can be saved (inserted)
010 * or processed yourself.
011 * <p>
012 * This first example doesn't use a {@link CsvCallback} and this means it will
013 * automatically create a transaction, save the customers and commit the
014 * transaction when successful.
015 * </p>
016 *
017 * <pre>{@code
018 * try {
019 *   File f = new File("src/test/resources/test1.csv");
020 *
021 *   FileReader reader = new FileReader(f);
022 *
023 *   CsvReader<Customer> csvReader = DB.createCsvReader(Customer.class);
024 *
025 *   csvReader.setPersistBatchSize(20);
026 *
027 *   csvReader.addProperty("status");
028 *   // ignore the next property
029 *   csvReader.addIgnore();
030 *   csvReader.addProperty("name");
031 *   csvReader.addDateTime("anniversary", "dd-MMM-yyyy");
032 *   csvReader.addProperty("billingAddress.line1");
033 *   csvReader.addProperty("billingAddress.city");
034 *
035 *   csvReader.process(reader);
036 *
037 * } catch (Exception e) {
038 *   throw new RuntimeException(e);
039 * }
040 * }</pre>
041 *
042 * @param <T> the entity bean type
043 */
044public interface CsvReader<T> {
045
046  /**
047   * Explicitly set the default Locale.
048   */
049  void setDefaultLocale(Locale defaultLocale);
050
051  /**
052   * Set the default format to use for Time types.
053   */
054  void setDefaultTimeFormat(String defaultTimeFormat);
055
056  /**
057   * Set the default format to use for Date types.
058   */
059  void setDefaultDateFormat(String defaultDateFormat);
060
061  /**
062   * Set the default format to use for Timestamp types.
063   */
064  void setDefaultTimestampFormat(String defaultTimestampFormat);
065
066  /**
067   * Set the batch size for using JDBC statement batching.
068   * <p>
069   * By default this is set to 20 and setting this to 1 will disable the use of
070   * JDBC statement batching.
071   * </p>
072   */
073  void setPersistBatchSize(int persistBatchSize);
074
075  /**
076   * Set to true if there is a header row that should be ignored.
077   * <p>
078   * If addPropertiesFromHeader is true then all the properties are added using
079   * the default time,date and timestamp formats.
080   * <p>
081   * If you have a mix of dateTime formats you can not use this method and must
082   * add the properties yourself.
083   * </p>
084   */
085  void setHasHeader(boolean hasHeader, boolean addPropertiesFromHeader);
086
087  /**
088   * Same as setHasHeader(true,true);
089   * <p>
090   * This will use a header to define all the properties to load using the
091   * default formats for time, date and datetime types.
092   * </p>
093   */
094  void setAddPropertiesFromHeader();
095
096  /**
097   * Same as setHasHeader(true, false);
098   * <p>
099   * This indicates that there is a header but that it should be ignored.
100   * </p>
101   */
102  void setIgnoreHeader();
103
104  /**
105   * Set the frequency with which a INFO message will be logged showing the
106   * progress of the processing. You might set this to 1000 or 10000 etc.
107   * <p>
108   * If this is not set then no INFO messages will be logged.
109   * </p>
110   */
111  void setLogInfoFrequency(int logInfoFrequency);
112
113  /**
114   * Ignore the next column of data.
115   */
116  void addIgnore();
117
118  /**
119   * Define the property which will be loaded from the next column of data.
120   * <p>
121   * This takes into account the data type of the property and handles the
122   * String to object conversion automatically.
123   * </p>
124   */
125  void addProperty(String propertyName);
126
127  /**
128   * Define the next property and use a custom StringParser to convert the
129   * string content into the appropriate type for the property.
130   */
131  void addProperty(String propertyName, StringParser parser);
132
133  /**
134   * Add a property with a custom Date/Time/Timestamp format using the default
135   * Locale. This will convert the string into the appropriate java type for the
136   * given property (Date, Calendar, SQL Date, Time, Timestamp, JODA etc).
137   */
138  void addDateTime(String propertyName, String dateTimeFormat);
139
140  /**
141   * Add a property with a custom Date/Time/Timestamp format. This will convert
142   * the string into the appropriate java type for the given property (Date,
143   * Calendar, SQL Date, Time, Timestamp, JODA etc).
144   */
145  void addDateTime(String propertyName, String dateTimeFormat, Locale locale);
146
147  /**
148   * Automatically create a transaction if required to process all the CSV
149   * content from the reader.
150   * <p>
151   * This will check for a current transaction. If there is no current
152   * transaction then one is started and will commit (or rollback) at the end of
153   * processing. This will also set the persistBatchSize on the transaction.
154   * </p>
155   */
156  void process(Reader reader) throws Exception;
157
158  /**
159   * Process the CSV content passing the bean to the CsvCallback after each row.
160   * <p>
161   * This provides you with the ability to modify and process the bean.
162   * </p>
163   * <p>
164   * When using a CsvCallback the reader WILL NOT create a transaction or save
165   * the bean(s) for you. If you want to insert the processed beans you must
166   * create your own transaction and save the bean(s) yourself.
167   * </p>
168   */
169  void process(Reader reader, CsvCallback<T> callback) throws Exception;
170
171}