View Javadoc
1   package org.csveed.api;
2   
3   import java.util.Collection;
4   import java.util.List;
5   import java.util.Locale;
6   
7   import org.csveed.bean.AbstractMapper;
8   import org.csveed.bean.conversion.Converter;
9   
10  /**
11  * <p>
12  *     The CsvClient is responsible for reading/writing CSV rows and converting those into beans/rows. There are a couple
13  *     of ways to initialize a {@link org.csveed.api.CsvClientImpl}:
14  * </p>
15  *
16  * <ul>
17  *     <li>Just use a Reader/Writer. In this case you can only use the row functionality of CSVeed,
18  *         not the bean functionality</li>
19  *     <li>Pass a Reader or Writer and point it to class. The {@link org.csveed.annotations} in the class are read,
20  *         as is the order
21  *         of the properties within the class.</li>
22  *     <li>Pass a Reader or Writer and roll your own instructions. Pass a {@link org.csveed.bean.BeanInstructions}
23  *         implementation with your own configuration settings</li>
24  * </ul>
25  *
26  * @param <T> the bean class into which the rows are converted
27  * @author Robert Bor
28  */
29  public interface CsvClient<T> {
30  
31      /**
32      * Writes a collection of Beans to the table
33      * @param beans beans to write to the table
34      */
35      void writeBeans(Collection<T> beans);
36  
37      /**
38      * Writes a single Bean to the table
39      * @param bean bean to write to the table
40      */
41      void writeBean(T bean);
42  
43      /**
44      * Writes a single row to the table
45      * @param row single row
46      */
47      void writeRow(Row row);
48  
49      /**
50      * Writes a single row (consisting of String cells) to the table
51      * @param row single row
52      * @return the written row
53      */
54      Row writeRow(String[] row);
55  
56      /**
57      * Writes a collection of rows to the table
58      * @param rows collections of rows
59      */
60      void writeRows(Collection<Row> rows);
61  
62      /**
63      * Writes a two-dimensional array of cells (rows with cells) to the table
64      * @param rows two-dimensional array of cells
65      */
66      void writeRows(String[][] rows);
67  
68      /**
69      * Writes the header to the table
70      * @param header the header row
71      * @return the converted Header
72      */
73      Header writeHeader(String[] header);
74  
75      /**
76      * Writes the header to the table
77      * @param header the header row
78      */
79      void writeHeader(Header header);
80  
81      /**
82       * Writes a header based on the bean properties to the table
83       */
84      void writeHeader();
85  
86      /**
87      * Reads all rows from the file and return these as beans.
88      * @return all beans read from the Reader
89      */
90      List<T> readBeans();
91  
92      /**
93      * Reads a single row and returns this as a bean. The RowReader will keep track of its state.
94      * @return Bean read from the Reader
95      */
96      T readBean();
97  
98      /**
99      * Reads all rows from the file and returns them as a List. After this, the RowReader will be finished
100     * @return all Rows read from the Reader
101     */
102     List<Row> readRows();
103 
104     /**
105     * Reads a single row from the file and returns this. The RowReader will keep track of its state.
106     * @return Row read from the Reader
107     */
108     Row readRow();
109 
110     /**
111     * Returns the header of the CSV file. Only possibly returns a value when useHeader==true
112     * @return header or null if the useHeader==false
113     */
114     Header readHeader();
115 
116     /**
117     * Returns the line from which the row was read. Note that a line is seen as a legitimate CSV row, not
118     * necessarily a printable line (unless multi-lines are used, these values are the same).
119     * @return current line number
120     */
121     int getCurrentLine();
122 
123     /**
124     * States whether the Reader is done with the file
125     * @return true if file is finished
126     */
127     boolean isFinished();
128 
129     /**
130     * Makes sure that the first readable line is interpreted as the header line. That line will not be read
131     * as content. This method is called whenever {@link org.csveed.annotations.CsvFile#useHeader()}
132     * is used. The default value for this setting is true. This call is a facade for
133     * {@link org.csveed.row.RowInstructions#setUseHeader(boolean)}.
134     * @param useHeader true if the header is interpreted and used
135     * @return convenience for chaining
136     */
137     CsvClient<T> setUseHeader(boolean useHeader);
138 
139     /**
140     * Sets the start row of the CSV file. If {@link #setUseHeader(boolean)} == true, this will be the header
141     * row and the next ones are all content rows. This method is called whenever
142     * {@link org.csveed.annotations.CsvFile#startRow()} is used. The default value for this
143     * setting is 1. This call is a facade for {@link org.csveed.row.RowInstructions#setStartRow(int)}.
144     * @param startRow the first row to start reading, including the header row
145     * @return convenience for chaining
146     */
147     CsvClient<T> setStartRow(int startRow);
148 
149     /**
150     * Sets the character that will be interpreted as an escape symbol while within a quoted field. This
151     * method is called whenever {@link org.csveed.annotations.CsvFile#escape()} is used. The
152     * default value for this setting is a double quote (") symbol. This call is a facade for
153     * {@link org.csveed.row.RowInstructions#setEscape(char)}.
154     * @param symbol the symbol to use for escaping characters within a quoted field
155     * @return convenience for chaining
156     */
157     CsvClient<T> setEscape(char symbol);
158 
159     /**
160     * Sets the character that will be interpreted as a quote symbol, signifying either the start or the
161     * end of a quoted field. This method is called whenever {@link org.csveed.annotations.CsvFile#quote()}
162     * is used. The default value for this setting is a double quote (") symbol. This call is a facade for
163     * {@link org.csveed.row.RowInstructions#setQuote(char)}.
164     * @param symbol the symbol to use for indicating start/end of a quoted field
165     * @return convenience for chaining
166     */
167     CsvClient<T> setQuote(char symbol);
168 
169     /**
170     * Sets the character that will be interpreted as a separator between cells. This method is called whenever
171     * {@link org.csveed.annotations.CsvFile#separator()} is used. The default value for this
172     * setting is a semi-colon (;). This call is a facade for {@link org.csveed.row.RowInstructions#setSeparator(char)}.
173     * @param symbol the symbol to use as a separator between cells
174     * @return convenience for chaining
175     */
176     CsvClient<T> setSeparator(char symbol);
177 
178     /**
179     * Sets the character that will be interpreted as a comment field on the first position of a row.
180     * This method is called whenever {@link org.csveed.annotations.CsvFile#comment()} is used.
181     * The default value for this setting is a hashtag (#).
182     * @param symbol the symbol to use as the 0-position comment marker
183     * @return convenience for chaining
184     */
185     CsvClient<T> setComment(char symbol);
186 
187     /**
188     * Sets the characters (plural) that will be interpreted as end-of-line markers (unless within a quoted
189     * field). This method is called whenever {@link org.csveed.annotations.CsvFile#endOfLine()}
190     * is used. The default values for this setting are \r and \n.  This call is a facade for
191     * {@link org.csveed.row.RowInstructions#setEndOfLine(char[])}.
192     * @param symbols the symbol to interpret as end-of-line markers (unless within a quoted field)
193     * @return convenience for chaining
194     */
195     CsvClient<T> setEndOfLine(char[] symbols);
196 
197     /**
198     * Determines whether empty lines must be skipped or treated as single-column rows. This method is called
199     * whenever {@link org.csveed.annotations.CsvFile#skipEmptyLines()} is used. The default
200     * value for this setting is to skip the empty lines.
201     * @param skip true to skip empty lines, false to treat as single-column rows
202     * @return convenience for chaining
203     */
204     CsvClient<T> skipEmptyLines(boolean skip);
205 
206     /**
207     * Determines whether comment lines must be skipped. This method is called whenever
208     * {@link org.csveed.annotations.CsvFile#skipCommentLines()}  is used. The default
209     * value for this setting is to skip comment lines. This method exists to guarantee that lines are
210     * not accidentally treated as comment lines.
211     * @param skip true to skip comment lines, identified as starting with a comment marker
212     * @return convenience for chaining
213     */
214     CsvClient<T> skipCommentLines(boolean skip);
215 
216     /**
217     * A file can have a special layout with a dynamic number of columns. If the intention is to duplicate rows
218     * for every separate column, this is the method you require. It will remember the start position of the
219     * dynamic columns and treat every column after that as dynamic. For every dynamic column a row will be
220     * created. If a bean has fields annotated with @CsvHeaderName or @CsvHeaderValue, it will store the
221     * values of the header or the cell for that index column in the fields.
222     * @param startIndex the index where the dynamic columns start
223     * @return convenience for chaining
224     */
225     CsvClient<T> setStartIndexDynamicColumns(int startIndex);
226 
227     /**
228     * Determines which mapping strategy is to be employed for mapping cells to bean properties. This
229     * method is called whenever {@link org.csveed.annotations.CsvFile#mappingStrategy()} is
230     * used. The default mapping strategy is {@link org.csveed.bean.ColumnIndexMapper}, which
231     * looks at either the position of a property within the class or the custom index if
232     * {@link org.csveed.annotations.CsvCell#columnIndex()} or {@link #mapColumnIndexToProperty(int, String)}
233     * has been set.
234     * @param mapper the mapping strategy to employ for mapping cells to bean properties
235     * @return convenience for chaining
236     */
237     CsvClient<T> setMapper(Class<? extends AbstractMapper> mapper);
238 
239     /**
240     * Determines what dateformat to apply to the cell value before storing it as a date. This method is called
241     * whenever {@link org.csveed.annotations.CsvDate} is used. The default for date format is
242     * dd-MM-yyyy.
243     * @param propertyName the name of the property to write the date to
244     * @param dateFormat the date format to apply for parsing the date value
245     * @return convenience for chaining
246     */
247     CsvClient<T> setDate(String propertyName, String dateFormat);
248 
249     /**
250     * Determines what Locale to apply to the cell value before converting it to a number. This method is called
251     * whenever {@link org.csveed.annotations.CsvLocalizedNumber} is used. The default for Locale is the Locale
252     * of the server.
253     * @param propertyName the name of the property to write the data to
254     * @param locale the Locale to apply for converting the number
255     * @return convenience for chaining
256     */
257     CsvClient<T> setLocalizedNumber(String propertyName, Locale locale);
258 
259     /**
260     * Determines if the field is required. If so, the cell may not be empty and a
261     * {@link org.csveed.report.CsvException} will be thrown if this occurs. This method is called
262     * whenever {@link org.csveed.annotations.CsvCell#required()} is used. The default for a property
263     * is false.
264     * @param propertyName property for which the requirement applies
265     * @param required whether the cell must be not-null
266     * @return convenience for chaining
267     */
268     CsvClient<T> setRequired(String propertyName, boolean required);
269 
270     /**
271     * Sets a custom {@link java.beans.PropertyEditor} for the property. This PropertyEditor is called to convert the
272     * text to the type of the property and set it on the bean. This method is called whenever
273     * {@link org.csveed.annotations.CsvConverter#converter()} is used. The default for a property
274     * is based on the wonderful set of PropertyEditors that Spring offers, which is all basics and some extras
275     * as well.
276     * @param propertyName property to which the converter must be applied
277     * @param converter PropertyEditor to apply to the property
278     * @return convenience for chaining
279     */
280     CsvClient<T> setConverter(String propertyName, Converter converter);
281 
282     /**
283     * Sets a field to be ignored for purposes of mapping. This method is called whenever
284     * {@link org.csveed.annotations.CsvIgnore} is used. By default none of the fields are ignored
285     * unless, custom instructions are used. In this case, all fields are ignored by default.
286     * @param propertyName property which must be ignored for mapping
287     * @return convenience for chaining
288     */
289     CsvClient<T> ignoreProperty(String propertyName);
290 
291     /**
292     * Maps a column in the CSV to a specific property. This method is called whenever
293     * {@link org.csveed.annotations.CsvCell#columnIndex()} is used. By default there is NO mapping
294     * when custom instructions are used, so you should roll your own. Note that column indexes are
295     * 1-based, not 0-based.
296     * @param columnIndex index of the column for which the property mapping must be applied
297     * @param propertyName property to which the index-based mapping must be applied
298     * @return convenience for chaining
299     */
300     CsvClient<T> mapColumnIndexToProperty(int columnIndex, String propertyName);
301 
302     /**
303     * Maps a column name (which is found in the header) to a specific property. Note that to use this, headers
304     * must be enabled. This method is called whenever {@link org.csveed.annotations.CsvCell#columnName()}
305     * is used. By default there is NO mapping when custom instructions are used, so you should roll your own.
306     * Also, don't forget to {@link #setMapper(Class)} to
307     * {@link org.csveed.bean.ColumnNameMapper} for this to work.
308     * @param columnName name of the column for which the property mapping must be applied
309     * @param propertyName property to which the name-based mapping must be applied
310     * @return convenience for chaining
311     */
312     CsvClient<T> mapColumnNameToProperty(String columnName, String propertyName);
313 
314     /**
315     * Determines what property will receive the header name in the currently active dynamic column
316     * @param propertyName property in which the active dynamic header name must be stored
317     * @return convenience for chaining
318     */
319     CsvClient<T> setHeaderNameToProperty(String propertyName);
320 
321     /**
322     * Determines what property will receive the cell value in the currently active dynamic column
323     * @param propertyName property in which the active dynamic column value must be stored
324     * @return convenience for chaining
325     */
326     CsvClient<T> setHeaderValueToProperty(String propertyName);
327 
328 }