1 /* 2 * Copyright 2007 Kasper B. Graversen 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.supercsv.io; 17 18 import java.io.IOException; 19 import java.util.List; 20 21 import org.supercsv.cellprocessor.ift.CellProcessor; 22 import org.supercsv.exception.SuperCsvConstraintViolationException; 23 import org.supercsv.exception.SuperCsvException; 24 25 /** 26 * Interface for readers that read into Lists. 27 * 28 * @author Kasper B. Graversen 29 * @author James Bassett 30 */ 31 public interface ICsvListReader extends ICsvReader { 32 33 /** 34 * Reads a row of a CSV file and returns a List of Strings containing each column. If you are forced to use this 35 * method instead of {@link #read(CellProcessor...)} because your CSV file has a variable number of columns, then 36 * you can call the {@link #executeProcessors(CellProcessor...)} method after calling {@link #read()} to execute the 37 * cell processors manually (after determining the number of columns read in and which cell processors to use). 38 * 39 * @return the List of columns, or null if EOF 40 * @throws IOException 41 * if an I/O error occurred 42 * @throws SuperCsvException 43 * if there was a general exception while reading/processing 44 * @since 1.0 45 */ 46 List<String> read() throws IOException; 47 48 /** 49 * Reads a row of a CSV file and returns a List of Objects containing each column. The data can be further processed 50 * by cell processors (each element in the processors array corresponds with a CSV column). A <tt>null</tt> entry in 51 * the processors array indicates no further processing is required (the unprocessed String value will be added to 52 * the List). Prior to version 2.0.0 this method returned a List of Strings. 53 * 54 * @param processors 55 * an array of CellProcessors used to further process data before it is added to the List (each element 56 * in the processors array corresponds with a CSV column - the number of processors should match the 57 * number of columns). A <tt>null</tt> entry indicates no further processing is required (the unprocessed 58 * String value will be added to the List). 59 * @return the List of columns, or null if EOF 60 * @throws IOException 61 * if an I/O error occurred 62 * @throws NullPointerException 63 * if processors is null 64 * @throws SuperCsvConstraintViolationException 65 * if a CellProcessor constraint failed 66 * @throws SuperCsvException 67 * if there was a general exception while reading/processing 68 * @since 1.0 69 */ 70 List<Object> read(CellProcessor... processors) throws IOException; 71 72 /** 73 * Executes the supplied cell processors on the last row of CSV that was read. This should only be used when the 74 * number of CSV columns is unknown before the row is read, and you are forced to use {@link #read()} instead of 75 * {@link #read(CellProcessor...)}. 76 * 77 * @param processors 78 * an array of CellProcessors used to further process the last row of CSV data that was read (each 79 * element in the processors array corresponds with a CSV column - the number of processors should match 80 * the number of columns). A <tt>null</tt> entry indicates no further processing is required (the 81 * unprocessed String value will be added to the List). 82 * @return the List of processed columns 83 * @throws NullPointerException 84 * if processors is null 85 * @throws SuperCsvConstraintViolationException 86 * if a CellProcessor constraint failed 87 * @throws SuperCsvException 88 * if the wrong number of processors are supplied, or CellProcessor execution failed 89 * @since 2.1.0 90 */ 91 List<Object> executeProcessors(CellProcessor... processors); 92 }