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.Map;
20
21 import org.supercsv.cellprocessor.ift.CellProcessor;
22 import org.supercsv.exception.SuperCsvConstraintViolationException;
23 import org.supercsv.exception.SuperCsvException;
24
25 /**
26 * The interface for MapReaders, which read each CSV row into a Map.
27 *
28 * @author Kasper B. Graversen
29 * @author James Bassett
30 */
31 public interface ICsvMapReader extends ICsvReader {
32
33 /**
34 * Reads a row of a CSV file into a Map, using the supplied name mapping to map column values to the appropriate map
35 * entries.
36 *
37 * @param nameMapping
38 * an array of Strings linking the CSV columns to their corresponding entry in the Map (the array length
39 * should match the number of columns). A <tt>null</tt> entry in the array indicates that the column
40 * should be ignored (e.g. not added to the Map).
41 * @return a Map of column names to column values (Strings, as no processing is performed), or null if EOF
42 * @throws IOException
43 * if an I/O error occurred
44 * @throws NullPointerException
45 * if nameMapping is null
46 * @throws SuperCsvException
47 * if there was a general exception while reading/processing
48 * @since 1.0
49 */
50 Map<String, String> read(String... nameMapping) throws IOException;
51
52 /**
53 * Reads a row of a CSV file into a Map, using the supplied name mapping to map column values to the appropriate map
54 * entries, and the supplied processors to process the values before adding them to the Map.
55 *
56 * @param nameMapping
57 * an array of Strings linking the CSV columns to their corresponding entry in the Map (the array length
58 * should match the number of columns). A <tt>null</tt> entry in the array indicates that the column
59 * should be ignored (e.g. not added to the Map).
60 * @param processors
61 * an array of CellProcessors used to further process data before it is added to the Map (each element in
62 * the processors array corresponds with a CSV column - the number of processors should match the number
63 * of columns). A <tt>null</tt> entry indicates no further processing is required (the unprocessed String
64 * value will added to the Map).
65 * @return a Map of column names to column values, or null if EOF
66 * @throws IOException
67 * if an I/O error occurred
68 * @throws NullPointerException
69 * if nameMapping or processors are null
70 * @throws SuperCsvConstraintViolationException
71 * if a CellProcessor constraint failed
72 * @throws SuperCsvException
73 * if there was a general exception while reading/processing
74 * @since 1.0
75 */
76 Map<String, Object> read(String[] nameMapping, CellProcessor[] processors) throws IOException;
77
78 }