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}