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