1 /*
2 * Copyright 2006-2007 the original author or authors.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package org.springframework.batch.item.file.transform;
17
18 import java.math.BigDecimal;
19 import java.sql.ResultSet;
20 import java.util.Date;
21 import java.util.Properties;
22
23 /**
24 * Interface used by flat file input sources to encapsulate concerns of
25 * converting an array of Strings to Java native types. A bit like the role
26 * played by {@link ResultSet} in JDBC, clients will know the name or position
27 * of strongly typed fields that they want to extract.
28 *
29 * @author Dave Syer
30 *
31 */
32 public interface FieldSet {
33
34 /**
35 * Accessor for the names of the fields.
36 *
37 * @return the names
38 *
39 * @throws IllegalStateException if the names are not defined
40 */
41 String[] getNames();
42
43 /**
44 * Check if there are names defined for the fields.
45 *
46 * @return true if there are names for the fields
47 */
48 boolean hasNames();
49
50 /**
51 * @return fields wrapped by this '<code>FieldSet</code>' instance as
52 * String values.
53 */
54 String[] getValues();
55
56 /**
57 * Read the {@link String} value at index '<code>index</code>'.
58 *
59 * @param index the field index.
60 * @throws IndexOutOfBoundsException if the index is out of bounds.
61 */
62 String readString(int index);
63
64 /**
65 * Read the {@link String} value from column with given '<code>name</code>'.
66 *
67 * @param name the field name.
68 */
69 String readString(String name);
70
71 /**
72 * Read the {@link String} value at index '<code>index</code>' including
73 * trailing whitespace (don't trim).
74 *
75 * @param index the field index.
76 * @throws IndexOutOfBoundsException if the index is out of bounds.
77 */
78 String readRawString(int index);
79
80 /**
81 * Read the {@link String} value from column with given '<code>name</code>'
82 * including trailing whitespace (don't trim).
83 *
84 * @param name the field name.
85 */
86 String readRawString(String name);
87
88 /**
89 * Read the '<code>boolean</code>' value at index '<code>index</code>'.
90 *
91 * @param index the field index.
92 * @throws IndexOutOfBoundsException if the index is out of bounds.
93 */
94 boolean readBoolean(int index);
95
96 /**
97 * Read the '<code>boolean</code>' value from column with given '<code>name</code>'.
98 *
99 * @param name the field name.
100 * @throws IllegalArgumentException if a column with given name is not
101 * defined.
102 */
103 boolean readBoolean(String name);
104
105 /**
106 * Read the '<code>boolean</code>' value at index '<code>index</code>'.
107 *
108 * @param index the field index.
109 * @param trueValue the value that signifies {@link Boolean#TRUE true};
110 * case-sensitive.
111 * @throws IndexOutOfBoundsException if the index is out of bounds, or if
112 * the supplied <code>trueValue</code> is <code>null</code>.
113 */
114 boolean readBoolean(int index, String trueValue);
115
116 /**
117 * Read the '<code>boolean</code>' value from column with given '<code>name</code>'.
118 *
119 * @param name the field name.
120 * @param trueValue the value that signifies {@link Boolean#TRUE true};
121 * case-sensitive.
122 * @throws IllegalArgumentException if a column with given name is not
123 * defined, or if the supplied <code>trueValue</code> is <code>null</code>.
124 */
125 boolean readBoolean(String name, String trueValue);
126
127 /**
128 * Read the '<code>char</code>' value at index '<code>index</code>'.
129 *
130 * @param index the field index.
131 * @throws IndexOutOfBoundsException if the index is out of bounds.
132 */
133 char readChar(int index);
134
135 /**
136 * Read the '<code>char</code>' value from column with given '<code>name</code>'.
137 *
138 * @param name the field name.
139 * @throws IllegalArgumentException if a column with given name is not
140 * defined.
141 */
142 char readChar(String name);
143
144 /**
145 * Read the '<code>byte</code>' value at index '<code>index</code>'.
146 *
147 * @param index the field index.
148 * @throws IndexOutOfBoundsException if the index is out of bounds.
149 */
150 byte readByte(int index);
151
152 /**
153 * Read the '<code>byte</code>' value from column with given '<code>name</code>'.
154 *
155 * @param name the field name.
156 */
157 byte readByte(String name);
158
159 /**
160 * Read the '<code>short</code>' value at index '<code>index</code>'.
161 *
162 * @param index the field index.
163 * @throws IndexOutOfBoundsException if the index is out of bounds.
164 */
165 short readShort(int index);
166
167 /**
168 * Read the '<code>short</code>' value from column with given '<code>name</code>'.
169 *
170 * @param name the field name.
171 * @throws IllegalArgumentException if a column with given name is not
172 * defined.
173 */
174 short readShort(String name);
175
176 /**
177 * Read the '<code>int</code>' value at index '<code>index</code>'.
178 *
179 * @param index the field index.
180 * @throws IndexOutOfBoundsException if the index is out of bounds.
181 */
182 int readInt(int index);
183
184 /**
185 * Read the '<code>int</code>' value from column with given '<code>name</code>'.
186 *
187 * @param name the field name.
188 * @throws IllegalArgumentException if a column with given name is not
189 * defined.
190 */
191 int readInt(String name);
192
193 /**
194 * Read the '<code>int</code>' value at index '<code>index</code>',
195 * using the supplied <code>defaultValue</code> if the field value is
196 * blank.
197 *
198 * @param index the field index..
199 * @throws IndexOutOfBoundsException if the index is out of bounds.
200 */
201 int readInt(int index, int defaultValue);
202
203 /**
204 * Read the '<code>int</code>' value from column with given '<code>name</code>',
205 * using the supplied <code>defaultValue</code> if the field value is
206 * blank.
207 *
208 * @param name the field name.
209 * @throws IllegalArgumentException if a column with given name is not
210 * defined.
211 */
212 int readInt(String name, int defaultValue);
213
214 /**
215 * Read the '<code>long</code>' value at index '<code>index</code>'.
216 *
217 * @param index the field index.
218 * @throws IndexOutOfBoundsException if the index is out of bounds.
219 */
220 long readLong(int index);
221
222 /**
223 * Read the '<code>long</code>' value from column with given '<code>name</code>'.
224 *
225 * @param name the field name.
226 * @throws IllegalArgumentException if a column with given name is not
227 * defined.
228 */
229 long readLong(String name);
230
231 /**
232 * Read the '<code>long</code>' value at index '<code>index</code>',
233 * using the supplied <code>defaultValue</code> if the field value is
234 * blank.
235 *
236 * @param index the field index..
237 * @throws IndexOutOfBoundsException if the index is out of bounds.
238 */
239 long readLong(int index, long defaultValue);
240
241 /**
242 * Read the '<code>long</code>' value from column with given '<code>name</code>',
243 * using the supplied <code>defaultValue</code> if the field value is
244 * blank.
245 *
246 * @param name the field name.
247 * @throws IllegalArgumentException if a column with given name is not
248 * defined.
249 */
250 long readLong(String name, long defaultValue);
251
252 /**
253 * Read the '<code>float</code>' value at index '<code>index</code>'.
254 *
255 * @param index the field index.
256 * @throws IndexOutOfBoundsException if the index is out of bounds.
257 */
258 float readFloat(int index);
259
260 /**
261 * Read the '<code>float</code>' value from column with given '<code>name</code>.
262 *
263 * @param name the field name.
264 * @throws IllegalArgumentException if a column with given name is not
265 * defined.
266 */
267 float readFloat(String name);
268
269 /**
270 * Read the '<code>double</code>' value at index '<code>index</code>'.
271 *
272 * @param index the field index.
273 * @throws IndexOutOfBoundsException if the index is out of bounds.
274 */
275 double readDouble(int index);
276
277 /**
278 * Read the '<code>double</code>' value from column with given '<code>name</code>.
279 *
280 * @param name the field name.
281 * @throws IllegalArgumentException if a column with given name is not
282 * defined.
283 */
284 double readDouble(String name);
285
286 /**
287 * Read the {@link java.math.BigDecimal} value at index '<code>index</code>'.
288 *
289 * @param index the field index.
290 * @throws IndexOutOfBoundsException if the index is out of bounds.
291 */
292 BigDecimal readBigDecimal(int index);
293
294 /**
295 * Read the {@link java.math.BigDecimal} value from column with given '<code>name</code>.
296 *
297 * @param name the field name.
298 * @throws IllegalArgumentException if a column with given name is not
299 * defined.
300 */
301 BigDecimal readBigDecimal(String name);
302
303 /**
304 * Read the {@link BigDecimal} value at index '<code>index</code>',
305 * returning the supplied <code>defaultValue</code> if the trimmed string
306 * value at index '<code>index</code>' is blank.
307 *
308 * @param index the field index.
309 * @throws IndexOutOfBoundsException if the index is out of bounds.
310 */
311 BigDecimal readBigDecimal(int index, BigDecimal defaultValue);
312
313 /**
314 * Read the {@link BigDecimal} value from column with given '<code>name</code>,
315 * returning the supplied <code>defaultValue</code> if the trimmed string
316 * value at index '<code>index</code>' is blank.
317 *
318 * @param name the field name.
319 * @param defaultValue the default value to use if the field is blank
320 * @throws IllegalArgumentException if a column with given name is not
321 * defined.
322 */
323 BigDecimal readBigDecimal(String name, BigDecimal defaultValue);
324
325 /**
326 * Read the <code>java.util.Date</code> value in default format at
327 * designated column <code>index</code>.
328 *
329 * @param index the field index.
330 * @throws IndexOutOfBoundsException if the index is out of bounds.
331 * @throws IllegalArgumentException if the value is not parseable
332 * @throws NullPointerException if the value is empty
333 */
334 Date readDate(int index);
335
336 /**
337 * Read the <code>java.sql.Date</code> value in given format from column
338 * with given <code>name</code>.
339 *
340 * @param name the field name.
341 * @throws IllegalArgumentException if a column with given name is not
342 * defined or if the value is not parseable
343 * @throws NullPointerException if the value is empty
344 */
345 Date readDate(String name);
346
347 /**
348 * Read the <code>java.util.Date</code> value in default format at
349 * designated column <code>index</code>.
350 *
351 * @param index the field index.
352 * @param defaultValue the default value to use if the field is blank
353 * @throws IndexOutOfBoundsException if the index is out of bounds.
354 * @throws IllegalArgumentException if the value is not parseable
355 * @throws NullPointerException if the value is empty
356 */
357 Date readDate(int index, Date defaultValue);
358
359 /**
360 * Read the <code>java.sql.Date</code> value in given format from column
361 * with given <code>name</code>.
362 *
363 * @param name the field name.
364 * @param defaultValue the default value to use if the field is blank
365 * @throws IllegalArgumentException if a column with given name is not
366 * defined.
367 */
368 Date readDate(String name, Date defaultValue);
369
370 /**
371 * Read the <code>java.util.Date</code> value in default format at
372 * designated column <code>index</code>.
373 *
374 * @param index the field index.
375 * @param pattern the pattern describing the date and time format
376 * @throws IndexOutOfBoundsException if the index is out of bounds.
377 * @throws IllegalArgumentException if the date cannot be parsed.
378 *
379 */
380 Date readDate(int index, String pattern);
381
382 /**
383 * Read the <code>java.sql.Date</code> value in given format from column
384 * with given <code>name</code>.
385 *
386 * @param name the field name.
387 * @param pattern the pattern describing the date and time format
388 * @throws IllegalArgumentException if a column with given name is not
389 * defined or if the specified field cannot be parsed
390 *
391 */
392 Date readDate(String name, String pattern);
393
394 /**
395 * Read the <code>java.util.Date</code> value in default format at
396 * designated column <code>index</code>.
397 *
398 * @param index the field index.
399 * @param pattern the pattern describing the date and time format
400 * @param defaultValue the default value to use if the field is blank
401 * @throws IndexOutOfBoundsException if the index is out of bounds.
402 * @throws IllegalArgumentException if the date cannot be parsed.
403 *
404 */
405 Date readDate(int index, String pattern, Date defaultValue);
406
407 /**
408 * Read the <code>java.sql.Date</code> value in given format from column
409 * with given <code>name</code>.
410 *
411 * @param name the field name.
412 * @param pattern the pattern describing the date and time format
413 * @param defaultValue the default value to use if the field is blank
414 * @throws IllegalArgumentException if a column with given name is not
415 * defined or if the specified field cannot be parsed
416 *
417 */
418 Date readDate(String name, String pattern, Date defaultValue);
419
420 /**
421 * Return the number of fields in this '<code>FieldSet</code>'.
422 */
423 int getFieldCount();
424
425 /**
426 * Construct name-value pairs from the field names and string values. Null
427 * values are omitted.
428 *
429 * @return some properties representing the field set.
430 *
431 * @throws IllegalStateException if the field name meta data is not
432 * available.
433 */
434 Properties getProperties();
435
436 }