001        /*
002 * Copyright 2006-2007 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *      https://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package org.springframework.batch.item.file.transform;
017
018import java.math.BigDecimal;
019import java.sql.ResultSet;
020import java.util.Date;
021import java.util.Properties;
022
023/**
024 * Interface used by flat file input sources to encapsulate concerns of
025 * converting an array of Strings to Java native types. A bit like the role
026 * played by {@link ResultSet} in JDBC, clients will know the name or position
027 * of strongly typed fields that they want to extract.
028 * 
029 * @author Dave Syer
030 * 
031 */
032public interface FieldSet {
033
034        /**
035         * Accessor for the names of the fields.
036         * 
037         * @return the names
038         * 
039         * @throws IllegalStateException if the names are not defined
040         */
041        String[] getNames();
042
043        /**
044         * Check if there are names defined for the fields.
045         * 
046         * @return true if there are names for the fields
047         */
048        boolean hasNames();
049
050        /**
051         * @return fields wrapped by this '<code>FieldSet</code>' instance as
052         * String values.
053         */
054        String[] getValues();
055
056        /**
057         * Read the {@link String} value at index '<code>index</code>'.
058         * 
059         * @param index the field index.
060         * @return {@link String} containing the value at the index.
061         *
062         * @throws IndexOutOfBoundsException if the {@code index} is out of bounds.
063         */
064        String readString(int index);
065
066        /**
067         * Read the {@link String} value from column with given '<code>name</code>'.
068         * 
069         * @param name the field {@code name}.
070         * @return {@link String} containing the value from the specified {@code name}.
071         */
072        String readString(String name);
073
074        /**
075         * Read the {@link String} value at index '<code>index</code>' including
076         * trailing whitespace (don't trim).
077         * 
078         * @param index the field index.
079         * @return {@link String} containing the value from the specified {@code index}.
080         *
081         * @throws IndexOutOfBoundsException if the {@code index} is out of bounds.
082         */
083        String readRawString(int index);
084
085        /**
086         * Read the {@link String} value from column with given '<code>name</code>'
087         * including trailing whitespace (don't trim).
088         * 
089         * @param name the field {@code name}.
090         * @return {@link String} containing the value from the specified {@code name}.
091         */
092        String readRawString(String name);
093
094        /**
095         * Read the '<code>boolean</code>' value at index '<code>index</code>'.
096         * 
097         * @param index the field index.
098         * @return boolean containing the value from the specified {@code index}.
099         *
100         * @throws IndexOutOfBoundsException if the {@code index} is out of bounds.
101         */
102        boolean readBoolean(int index);
103
104        /**
105         * Read the '<code>boolean</code>' value from column with given '<code>name</code>'.
106         * 
107         * @param name the field {@code name}.
108         * @return boolean containing the value from the specified {@code name}.
109         *
110         * @throws IllegalArgumentException if a column with given {@code name} is not
111         * defined.
112         */
113        boolean readBoolean(String name);
114
115        /**
116         * Read the '<code>boolean</code>' value at index '<code>index</code>'.
117         * 
118         * @param index the field index.
119         * @param trueValue the value that signifies {@link Boolean#TRUE true};
120         * case-sensitive.
121         * @return boolean containing the value from the specified {@code index}.
122         *
123         * @throws IndexOutOfBoundsException if the index is out of bounds, or if
124         * the supplied <code>trueValue</code> is <code>null</code>.
125         */
126        boolean readBoolean(int index, String trueValue);
127
128        /**
129         * Read the '<code>boolean</code>' value from column with given '<code>name</code>'.
130         * 
131         * @param name the field {@code name}.
132         * @param trueValue the value that signifies {@link Boolean#TRUE true};
133         * case-sensitive.
134         * @return boolean containing the value from the specified {@code name}.
135         *
136         * @throws IllegalArgumentException if a column with given {@code name} is not
137         * defined, or if the supplied <code>trueValue</code> is <code>null</code>.
138         */
139        boolean readBoolean(String name, String trueValue);
140
141        /**
142         * Read the '<code>char</code>' value at index '<code>index</code>'.
143         * 
144         * @param index the field index.
145         * @return char containing the value from the specified {@code index}.
146         *
147         * @throws IndexOutOfBoundsException if the index is out of bounds.
148         */
149        char readChar(int index);
150
151        /**
152         * Read the '<code>char</code>' value from column with given '<code>name</code>'.
153         * 
154         * @param name the field {@code name}.
155         * @return char containing the value from the specified {@code name}.
156         *
157         * @throws IllegalArgumentException if a column with given {@code name} is not
158         * defined.
159         */
160        char readChar(String name);
161
162        /**
163         * Read the '<code>byte</code>' value at index '<code>index</code>'.
164         * 
165         * @param index the field index.
166         * @return byte containing the value from the specified {@code index}.
167         *
168         * @throws IndexOutOfBoundsException if the index is out of bounds.
169         */
170        byte readByte(int index);
171
172        /**
173         * Read the '<code>byte</code>' value from column with given '<code>name</code>'.
174         * 
175         * @param name the field {@code name}.
176         * @return byte containing the value from the specified {@code name}.
177         */
178        byte readByte(String name);
179
180        /**
181         * Read the '<code>short</code>' value at index '<code>index</code>'.
182         * 
183         * @param index the field {@code index}.
184         * @return short containing the value from the specified index.
185         *
186         * @throws IndexOutOfBoundsException if the index is out of bounds.
187         */
188        short readShort(int index);
189
190        /**
191         * Read the '<code>short</code>' value from column with given '<code>name</code>'.
192         * 
193         * @param name the field {@code name}.
194         * @return short containing the value from the specified {@code name}.
195         *
196         * @throws IllegalArgumentException if a column with given {@code name} is not
197         * defined.
198         */
199        short readShort(String name);
200
201        /**
202         * Read the '<code>int</code>' value at index '<code>index</code>'.
203         * 
204         * @param index the field index.
205         * @return int containing the value from the specified index.
206         *
207         * @throws IndexOutOfBoundsException if the index is out of bounds.
208         */
209        int readInt(int index);
210
211        /**
212         * Read the '<code>int</code>' value from column with given '<code>name</code>'.
213         * 
214         * @param name the field {@code name}.
215         * @return int containing the value from the specified {@code name}.
216         *
217         * @throws IllegalArgumentException if a column with given {@code name} is not
218         * defined.
219         */
220        int readInt(String name);
221
222        /**
223         * Read the '<code>int</code>' value at index '<code>index</code>',
224         * using the supplied <code>defaultValue</code> if the field value is
225         * blank.
226         * 
227         * @param index the field index.
228         * @param defaultValue the value to use if the field value is blank.
229         * @return int containing the value from the specified index.
230         *
231         * @throws IndexOutOfBoundsException if the index is out of bounds.
232         */
233        int readInt(int index, int defaultValue);
234
235        /**
236         * Read the '<code>int</code>' value from column with given '<code>name</code>',
237         * using the supplied <code>defaultValue</code> if the field value is
238         * blank.
239         * 
240         * @param name the field {@code name}.
241         * @param defaultValue the value to use if the field value is blank.
242         * @return int containing the value from the specified {@code name}.
243         *
244         * @throws IllegalArgumentException if a column with given {@code name} is not
245         * defined.
246         */
247        int readInt(String name, int defaultValue);
248
249        /**
250         * Read the '<code>long</code>' value at index '<code>index</code>'.
251         * 
252         * @param index the field index.
253         * @return long containing the value from the specified index.
254         *
255         * @throws IndexOutOfBoundsException if the index is out of bounds.
256         */
257        long readLong(int index);
258
259        /**
260         * Read the '<code>long</code>' value from column with given '<code>name</code>'.
261         * 
262         * @param name the field {@code name}.
263         * @return long containing the value from the specified {@code name}.
264         *
265         * @throws IllegalArgumentException if a column with given {@code name} is not
266         * defined.
267         */
268        long readLong(String name);
269
270        /**
271         * Read the '<code>long</code>' value at index '<code>index</code>',
272         * using the supplied <code>defaultValue</code> if the field value is
273         * blank.
274         * 
275         * @param index the field index.
276         * @param defaultValue the value to use if the field value is blank.
277         * @return long containing the value from the specified index.
278         *
279         * @throws IndexOutOfBoundsException if the index is out of bounds.
280         */
281        long readLong(int index, long defaultValue);
282
283        /**
284         * Read the '<code>long</code>' value from column with given '<code>name</code>',
285         * using the supplied <code>defaultValue</code> if the field value is
286         * blank.
287         * 
288         * @param name the field {@code name}.
289         * @param defaultValue the value to use if the field value is blank.
290         * @return long containing the value from the specified {@code name}.
291         *
292         * @throws IllegalArgumentException if a column with given {@code name} is not
293         * defined.
294         */
295        long readLong(String name, long defaultValue);
296
297        /**
298         * Read the '<code>float</code>' value at index '<code>index</code>'.
299         * 
300         * @param index the field index.
301         * @return float containing the value from the specified index.
302         *
303         * @throws IndexOutOfBoundsException if the index is out of bounds.
304         */
305        float readFloat(int index);
306
307        /**
308         * Read the '<code>float</code>' value from column with given '<code>name</code>.
309         * 
310         * @param name the field {@code name}.
311         * @return float containing the value from the specified {@code name}.
312         *
313         * @throws IllegalArgumentException if a column with given {@code name} is not
314         * defined.
315         */
316        float readFloat(String name);
317
318        /**
319         * Read the '<code>double</code>' value at index '<code>index</code>'.
320         * 
321         * @param index the field index.
322         * @return double containing the value from the specified index.
323         *
324         * @throws IndexOutOfBoundsException if the index is out of bounds.
325         */
326        double readDouble(int index);
327
328        /**
329         * Read the '<code>double</code>' value from column with given '<code>name</code>.
330         * 
331         * @param name the field {@code name}.
332         * @return double containing the value from the specified {@code name}.
333         *
334         * @throws IllegalArgumentException if a column with given {@code name} is not
335         * defined.
336         */
337        double readDouble(String name);
338
339        /**
340         * Read the {@link java.math.BigDecimal} value at index '<code>index</code>'.
341         * 
342         * @param index the field index.
343         * @return {@link BigDecimal} containing the value from the specified index.
344         *
345         * @throws IndexOutOfBoundsException if the index is out of bounds.
346         */
347        BigDecimal readBigDecimal(int index);
348
349        /**
350         * Read the {@link java.math.BigDecimal} value from column with given '<code>name</code>.
351         * 
352         * @param name the field {@code name}.
353         * @return {@link BigDecimal} containing the value from the specified {@code name}.
354         *
355         * @throws IllegalArgumentException if a column with given {@code name} is not
356         * defined.
357         */
358        BigDecimal readBigDecimal(String name);
359
360        /**
361         * Read the {@link BigDecimal} value at index '<code>index</code>',
362         * returning the supplied <code>defaultValue</code> if the trimmed string
363         * value at index '<code>index</code>' is blank.
364         * 
365         * @param index the field index.
366         * @param defaultValue the value to use if the field value is blank.
367         * @return {@link BigDecimal} containing the value from the specified index.
368         *
369         * @throws IndexOutOfBoundsException if the index is out of bounds.
370         */
371        BigDecimal readBigDecimal(int index, BigDecimal defaultValue);
372
373        /**
374         * Read the {@link BigDecimal} value from column with given '<code>name</code>,
375         * returning the supplied <code>defaultValue</code> if the trimmed string
376         * value at index '<code>index</code>' is blank.
377         * 
378         * @param name the field {@code name}.
379         * @param defaultValue the default value to use if the field is blank
380         * @return {@link BigDecimal} containing the value from the specified {@code name}.
381         *
382         * @throws IllegalArgumentException if a column with given {@code name} is not
383         * defined.
384         */
385        BigDecimal readBigDecimal(String name, BigDecimal defaultValue);
386
387        /**
388         * Read the <code>java.util.Date</code> value in default format at
389         * designated column <code>index</code>.
390         * 
391         * @param index the field index.
392         * @return {@link Date} containing the value from the specified index.
393         *
394         * @throws IndexOutOfBoundsException if the index is out of bounds.
395         * @throws IllegalArgumentException if the value is not parseable
396         * @throws NullPointerException if the value is empty
397         */
398        Date readDate(int index);
399
400        /**
401         * Read the <code>java.sql.Date</code> value in given format from column
402         * with given <code>name</code>.
403         * 
404         * @param name the field {@code name}.
405         * @return {@link Date} containing the value from the specified {@code name}.
406         *
407         * @throws IllegalArgumentException if a column with given {@code name} is not
408         * defined or if the value is not parseable
409         * @throws NullPointerException if the value is empty
410         */
411        Date readDate(String name);
412
413        /**
414         * Read the <code>java.util.Date</code> value in default format at
415         * designated column <code>index</code>.
416         * 
417         * @param index the field index.
418         * @param defaultValue the default value to use if the field is blank
419         * @return {@link Date} containing the value from the specified index.
420         *
421         * @throws IndexOutOfBoundsException if the index is out of bounds.
422         * @throws IllegalArgumentException if the value is not parseable
423         * @throws NullPointerException if the value is empty
424         */
425        Date readDate(int index, Date defaultValue);
426
427        /**
428         * Read the <code>java.sql.Date</code> value in given format from column
429         * with given <code>name</code>.
430         * 
431         * @param name the field {@code name}.
432         * @param defaultValue the default value to use if the field is blank
433         * @return {@link Date} containing the value from the specified {@code name}.
434         *
435         * @throws IllegalArgumentException if a column with given {@code name} is not
436         * defined.
437         */
438        Date readDate(String name, Date defaultValue);
439
440        /**
441         * Read the <code>java.util.Date</code> value in default format at
442         * designated column <code>index</code>.
443         * 
444         * @param index the field index.
445         * @param pattern the pattern describing the date and time format
446         * @return {@link Date} containing the value from the specified index.
447         *
448         * @throws IndexOutOfBoundsException if the index is out of bounds.
449         * @throws IllegalArgumentException if the date cannot be parsed.
450         * 
451         */
452        Date readDate(int index, String pattern);
453
454        /**
455         * Read the <code>java.sql.Date</code> value in given format from column
456         * with given <code>name</code>.
457         * 
458         * @param name the field {@code name}.
459         * @param pattern the pattern describing the date and time format
460         * @return {@link Date} containing the value from the specified {@code name}.
461         *
462         * @throws IllegalArgumentException if a column with given {@code name} is not
463         * defined or if the specified field cannot be parsed
464         * 
465         */
466        Date readDate(String name, String pattern);
467
468        /**
469         * Read the <code>java.util.Date</code> value in default format at
470         * designated column <code>index</code>.
471         * 
472         * @param index the field index.
473         * @param pattern the pattern describing the date and time format
474         * @param defaultValue the default value to use if the field is blank
475         * @return {@link Date} containing the value from the specified index.
476         *
477         * @throws IndexOutOfBoundsException if the index is out of bounds.
478         * @throws IllegalArgumentException if the date cannot be parsed.
479         * 
480         */
481        Date readDate(int index, String pattern, Date defaultValue);
482
483        /**
484         * Read the <code>java.sql.Date</code> value in given format from column
485         * with given <code>name</code>.
486         * 
487         * @param name the field {@code name}.
488         * @param pattern the pattern describing the date and time format
489         * @param defaultValue the default value to use if the field is blank
490         * @return {@link Date} containing the value from the specified {@code name}.
491         *
492         * @throws IllegalArgumentException if a column with given {@code name} is not
493         * defined or if the specified field cannot be parsed
494         * 
495         */
496        Date readDate(String name, String pattern, Date defaultValue);
497
498        /**
499         * Return the number of fields in this '<code>FieldSet</code>'.
500         *
501         * @return int containing the number of fields in this field set.
502         */
503        int getFieldCount();
504
505        /**
506         * Construct name-value pairs from the field names and string values. Null
507         * values are omitted.
508         * 
509         * @return some properties representing the field set.
510         * 
511         * @throws IllegalStateException if the field name meta data is not
512         * available.
513         */
514        Properties getProperties();
515
516}