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