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.SuperCsvConstraintViolationException; 23 import org.supercsv.exception.SuperCsvException; 24 import org.supercsv.io.ICsvWriter; 25 26 /** 27 * Interface for CSV writers writing objects/beans to CSV using Dozer. 28 * 29 * @author James Bassett 30 * @since 2.0.0 31 */ 32 public interface ICsvDozerBeanWriter extends ICsvWriter { 33 34 /** 35 * Configures the underlying DozerBeanMapper with the mappings required to map from the specified class to the CSV 36 * file (this method may only be called before writing, as it's not possible to configure a DozerBeanMapper that has 37 * already been initialized). Generally this method will only be called once, but it may called more times to add 38 * mappings for other classes (you can define mappings for two different subclasses for example, but if you define a 39 * mapping for the parent class then that will take precedence - inheritance mapping isn't supported). 40 * <p> 41 * Each element of the fieldMapping array represents a CSV column to be written and uses the standard Dozer field 42 * mapping syntax. For example, if you were configuring the mappings for Person class you might define 43 * <tt>firstName</tt> as the first element (just a simple field mapping), <tt>address.city</tt> as the second 44 * element (a nested - or deep - field mapping), and 45 * <tt>accounts[0].balance</tt> as the third element (index based mapping). 46 * <p> 47 * If you require access to the other features of Dozer in your mappings (customer getters/setters, bean factories, custom converters), 48 * then you should supply your own DozerBeanMapper to the Writer instead. 49 * 50 * @param clazz 51 * the class to add mapping configuration for (same as the type passed into write methods) 52 * @param fieldMapping 53 * the field mapping for for each column (cannot contain <tt>null</tt> elements) 54 * @throws NullPointerException 55 * if clazz or fieldMapping (or one of its elements) is null 56 * @since 2.0.0 57 */ 58 void configureBeanMapping(Class<?> clazz, String[] fieldMapping); 59 60 /** 61 * Writes the fields of the object as columns of a CSV file, using the pre-configured DozerBeanMapper to map fields 62 * to the appropriate columns. <tt>toString()</tt> will be called on each element prior to writing. 63 * 64 * @param source 65 * the object (bean instance) containing the values to write 66 * @throws IOException 67 * if an I/O error occurred 68 * @throws MappingException 69 * if there was an exception during Dozer mapping 70 * @throws NullPointerException 71 * if source is null 72 * @throws SuperCsvException 73 * if there was a general exception while writing 74 * @since 2.0.0 75 */ 76 void write(Object source) throws IOException; 77 78 /** 79 * Writes the fields of the object as columns of a CSV file, using the pre-configured DozerBeanMapper to map fields 80 * to the appropriate columns. 81 * <p> 82 * Before writing, the data can be further processed by cell processors (each element in the processors array 83 * corresponds with a CSV column). A <tt>null</tt> entry in the processors array indicates no further processing is 84 * required (the value returned by toString() will be written as the column value). <tt>toString()</tt> will be 85 * called on each (processed) element prior to writing. 86 * 87 * @param source 88 * the object (bean instance) containing the values to write 89 * @param processors 90 * an array of CellProcessors used to further process data before it is written (each element in the 91 * processors array corresponds with a CSV column - the number of processors should match the number of 92 * columns). A <tt>null</tt> entry indicates no further processing is required (the value returned by 93 * toString() will be written as the column value). 94 * @throws IOException 95 * if an I/O error occurred 96 * @throws MappingException 97 * if there was an exception during Dozer mapping 98 * @throws NullPointerException 99 * if source, nameMapping or processors are null 100 * @throws SuperCsvConstraintViolationException 101 * if a CellProcessor constraint failed 102 * @throws SuperCsvException 103 * if there was a general exception while writing/processing 104 * @since 2.0.0 105 */ 106 void write(Object source, CellProcessor[] processors) throws IOException; 107 108 }