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.dozer;
17
18 import java.io.IOException;
19
20 import org.dozer.MappingException;
21 import org.supercsv.cellprocessor.ift.CellProcessor;
22 import org.supercsv.exception.SuperCsvException;
23 import org.supercsv.io.ICsvReader;
24
25 /**
26 * Interface for CSV readers reading into objects/beans using Dozer.
27 *
28 * @author James Bassett
29 * @since 2.0.0
30 */
31 public interface ICsvDozerBeanReader extends ICsvReader {
32
33 /**
34 * Configures the underlying DozerBeanMapper with the mappings required to map from the CSV file to the specified
35 * class (this method may only be called before reading, as it's not possible to configure a DozerBeanMapper that
36 * has already been initialized). Generally this method will only be called once, but it may called more times to
37 * add mappings for other classes (you can define mappings for two different subclasses for example, but if you
38 * define a mapping for the parent class then that will take precedence - inheritance mapping isn't supported).
39 * <p>
40 * Each element of the fieldMapping array represents a CSV column to be read and uses the standard Dozer field
41 * mapping syntax. For example, if you were configuring the mappings for Person class you might define
42 * <tt>firstName</tt> as the first element (just a simple field mapping), <tt>address.city</tt> as the second
43 * element (a nested - or deep - field mapping), and <tt>accounts[0].balance</tt> as the third element (index based
44 * mapping).
45 * <p>
46 * If you require access to the other features of Dozer in your mappings (customer getters/setters, bean factories,
47 * custom converters), then you should supply your own DozerBeanMapper to the Writer instead.
48 *
49 * @param clazz
50 * the class to add mapping configuration for (same as the type passed into write methods)
51 * @param fieldMapping
52 * the field mapping for for each column (may contain <tt>null</tt> elements to indicate ignored columns)
53 * @throws NullPointerException
54 * if clazz or fieldMapping is null
55 * @since 2.0.0
56 */
57 void configureBeanMapping(Class<?> clazz, String[] fieldMapping);
58
59 /**
60 * Configures the underlying DozerBeanMapper with the mappings required to map from the CSV file to the specified
61 * class (this method may only be called before reading, as it's not possible to configure a DozerBeanMapper that
62 * has already been initialized). Generally this method will only be called once, but it may called more times to
63 * add mappings for other classes (you can define mappings for two different subclasses for example, but if you
64 * define a mapping for the parent class then that will take precedence - inheritance mapping isn't supported).
65 * <p>
66 * Each element of the fieldMapping array represents a CSV column to be read and uses the standard Dozer field
67 * mapping syntax. For example, if you were configuring the mappings for Person class you might define
68 * <tt>firstName</tt> as the first element (just a simple field mapping), <tt>address.city</tt> as the second
69 * element (a nested - or deep - field mapping), and <tt>accounts[0].balance</tt> as the third element (index based
70 * mapping).
71 * <p>
72 * If you are mapping to an indexed list element (e.g. <tt>accounts[0]</tt>) and using a cell processor to return a
73 * custom bean type (e.g. a <tt>ParseAccount</tt> processor that creates an <tt>Account</tt> bean), you will need to
74 * specify a hint for that column so Dozer can map that column.
75 * <p>
76 * If you require access to the other features of Dozer in your mappings (customer getters/setters, bean factories,
77 * custom converters), then you should supply your own DozerBeanMapper to the Writer instead.
78 *
79 * @param clazz
80 * the class to add mapping configuration for (same as the type passed into write methods)
81 * @param fieldMapping
82 * the field mapping for for each column (may contain <tt>null</tt> elements to indicate ignored columns)
83 * @param hintTypes
84 * an array of types used as hints for Dozer when mapping to an indexed list element (e.g.
85 * <tt>accounts[0]</tt>) - a null element indicates no hint is required for that column
86 * @throws NullPointerException
87 * if clazz, fieldMapping, or hintTypes is null
88 * @throws IllegalArgumentException
89 * if fieldMapping.length != hintTypes.length
90 * @since 2.1.0
91 */
92 void configureBeanMapping(Class<?> clazz, String[] fieldMapping, Class<?>[] hintTypes);
93
94 /**
95 * Reads a row of a CSV file and populates an instance of the specified class, using Dozer to map column values to
96 * the appropriate fields.
97 *
98 * @param clazz
99 * the type to instantiate
100 * @param <T>
101 * the bean type
102 * @return a populated bean or null if EOF
103 * @throws IOException
104 * if an I/O error occurred
105 * @throws MappingException
106 * if there was an exception during Dozer mapping
107 * @throws NullPointerException
108 * if clazz is null
109 * @throws SuperCsvException
110 * if there was a general exception while reading/processing
111 * @since 2.0.0
112 */
113 <T> T read(Class<T> clazz) throws IOException;
114
115 /**
116 * Reads a row of a CSV file and populates the supplied bean, using Dozer to map column values to the appropriate
117 * fields.
118 *
119 * @param bean
120 * the bean to populate
121 * @param <T>
122 * the bean type
123 * @return a populated bean or null if EOF
124 * @throws IOException
125 * if an I/O error occurred
126 * @throws MappingException
127 * if there was an exception during Dozer mapping
128 * @throws NullPointerException
129 * if bean is null
130 * @throws SuperCsvException
131 * if there was a general exception while reading/processing
132 * @since 2.2.0
133 */
134 <T> T read(T bean) throws IOException;
135
136 /**
137 * Reads a row of a CSV file and populates an instance of the specified class, using Dozer to map column values to
138 * the appropriate fields. Before population the data can be further processed by cell processors (each element in
139 * the processors array corresponds with a CSV column). A <tt>null</tt> entry in the processors array indicates no
140 * further processing is required (the unprocessed String value will be set on the bean's field) - though Dozer will
141 * attempt some conversions of it's own it the types don't match.
142 *
143 * @param clazz
144 * the type to instantiate
145 * @param processors
146 * the cell processors
147 * @param <T>
148 * the bean type
149 * @return a populated bean or null if EOF
150 * @throws IOException
151 * if an I/O error occurred
152 * @throws MappingException
153 * if there was an exception during Dozer mapping
154 * @throws NullPointerException
155 * if clazz is null
156 * @throws SuperCsvException
157 * if there was a general exception while reading/processing
158 * @since 2.0.0
159 */
160 <T> T read(Class<T> clazz, CellProcessor... processors) throws IOException;
161
162 /**
163 * Reads a row of a CSV file and populates the supplied bean, using Dozer to map column values to the appropriate
164 * fields. Before population the data can be further processed by cell processors (each element in the processors
165 * array corresponds with a CSV column). A <tt>null</tt> entry in the processors array indicates no further
166 * processing is required (the unprocessed String value will be set on the bean's field) - though Dozer will attempt
167 * some conversions of it's own it the types don't match.
168 *
169 * @param bean
170 * the bean to populate
171 * @param processors
172 * the cell processors
173 * @param <T>
174 * the bean type
175 * @return a populated bean or null if EOF
176 * @throws IOException
177 * if an I/O error occurred
178 * @throws MappingException
179 * if there was an exception during Dozer mapping
180 * @throws NullPointerException
181 * if bean is null
182 * @throws SuperCsvException
183 * if there was a general exception while reading/processing
184 * @since 2.2.0
185 */
186 <T> T read(T bean, CellProcessor... processors) throws IOException;
187
188 }