1 package com.opencsv;
2
3 import java.io.Closeable;
4 import java.io.Flushable;
5 import java.io.IOException;
6 import java.sql.ResultSet;
7 import java.sql.SQLException;
8 import java.util.List;
9
10 /**
11 * This interface defines all the behavior of a csv writer class.
12 *
13 * @since 4.2
14 */
15 public interface ICSVWriter extends Closeable, Flushable {
16 /**
17 * Default line terminator.
18 */
19 String DEFAULT_LINE_END = "\n";
20 /**
21 * RFC 4180 compliant line terminator.
22 */
23 String RFC4180_LINE_END = "\r\n";
24 /**
25 * Default buffer sizes
26 */
27 int INITIAL_STRING_SIZE = 1024;
28 /**
29 * The character used for escaping quotes.
30 */
31 char DEFAULT_ESCAPE_CHARACTER = '"';
32 /**
33 * The default separator to use if none is supplied to the constructor.
34 */
35 char DEFAULT_SEPARATOR = ',';
36 /**
37 * The default quote character to use if none is supplied to the
38 * constructor.
39 */
40 char DEFAULT_QUOTE_CHARACTER = '"';
41 /**
42 * The quote constant to use when you wish to suppress all quoting.
43 */
44 char NO_QUOTE_CHARACTER = '\u0000';
45 /**
46 * The escape constant to use when you wish to suppress all escaping.
47 */
48 char NO_ESCAPE_CHARACTER = '\u0000';
49
50
51 /**
52 * Writes iterable to a CSV file. The list is assumed to be a String[]
53 *
54 * @param allLines an Iterable of String[], with each String[] representing a line of
55 * the file.
56 * @param applyQuotesToAll true if all values are to be quoted. false if quotes only
57 * to be applied to values which contain the separator, escape,
58 * quote or new line characters.
59 */
60 void writeAll(Iterable<String[]> allLines, boolean applyQuotesToAll);
61
62 /**
63 * Writes the entire list to a CSV file.
64 * The list is assumed to be a String[].
65 *
66 * @param allLines A List of String[] with each String[] representing a line of
67 * the file.
68 * @param applyQuotesToAll True if all values are to be quoted. False if quotes only
69 * to be applied to values which contain the separator, escape,
70 * quote, or new line characters.
71 */
72 default void writeAll(List<String[]> allLines, boolean applyQuotesToAll) {
73 writeAll((Iterable<String[]>) allLines, applyQuotesToAll);
74 }
75
76 /**
77 * Writes iterable to a CSV file. The list is assumed to be a String[]
78 *
79 * @param allLines an Iterable of String[], with each String[] representing a line of
80 * the file.
81 */
82 default void writeAll(Iterable<String[]> allLines) {writeAll(allLines, true);}
83
84 /**
85 * Writes the entire list to a CSV file.
86 * The list is assumed to be a String[].
87 *
88 * @param allLines A List of String[] with each String[] representing a line of
89 * the file.
90 */
91 default void writeAll(List<String[]> allLines) {
92 writeAll((Iterable<String[]>) allLines);
93 }
94
95 /**
96 * Writes the entire ResultSet to a CSV file.
97 * <p>
98 * The caller is responsible for closing the ResultSet. Values are not trimmed.
99 * Quotes are applied to all values in the output.
100 *
101 * @param rs The result set to write
102 * @param includeColumnNames True if you want column names in the output, false otherwise
103 * @return Number of lines written.
104 * @throws java.io.IOException Thrown by ResultSetHelper.getColumnValues()
105 * @throws java.sql.SQLException Thrown by ResultSetHelper.getColumnValues()
106 */
107 default int writeAll(ResultSet rs, boolean includeColumnNames) throws SQLException, IOException {
108 return writeAll(rs, includeColumnNames, false, true);
109 }
110
111 /**
112 * Writes the entire ResultSet to a CSV file.
113 * <p>
114 * The caller is responsible for closing the ResultSet. Quotes are applied to
115 * all values in the output.
116 *
117 * @param rs The Result set to write.
118 * @param includeColumnNames Include the column names in the output.
119 * @param trim Remove spaces from the data before writing.
120 * @return Number of lines written - including header.
121 * @throws java.io.IOException Thrown by ResultSetHelper.getColumnValues()
122 * @throws java.sql.SQLException Thrown by ResultSetHelper.getColumnValues()
123 */
124 default int writeAll(ResultSet rs, boolean includeColumnNames, boolean trim) throws SQLException, IOException {
125 return writeAll(rs, includeColumnNames, trim, true);
126 }
127
128 /**
129 * Writes the entire ResultSet to a CSV file.
130 *
131 * The caller is responsible for closing the ResultSet.
132 *
133 * @param rs The Result set to write.
134 * @param includeColumnNames Include the column names in the output.
135 * @param trim Remove spaces from the data before writing.
136 * @param applyQuotesToAll Whether all values should be quoted.
137 *
138 * @throws java.io.IOException Thrown by ResultSetHelper.getColumnValues()
139 * @throws java.sql.SQLException Thrown by ResultSetHelper.getColumnValues()
140 *
141 * @return Number of lines written - including header.
142 */
143 int writeAll(ResultSet rs, boolean includeColumnNames, boolean trim, boolean applyQuotesToAll) throws SQLException, IOException;
144
145 /**
146 * Writes the next line to the file.
147 *
148 * @param nextLine A string array with each comma-separated element as a separate
149 * entry.
150 * @param applyQuotesToAll True if all values are to be quoted. False applies quotes only
151 * to values which contain the separator, escape, quote, or new line characters.
152 */
153 void writeNext(String[] nextLine, boolean applyQuotesToAll);
154
155 /**
156 * Writes the next line to the file.
157 *
158 * @param nextLine A string array with each comma-separated element as a separate
159 * entry.
160 */
161 default void writeNext(String[] nextLine) {
162 writeNext(nextLine, true);
163 }
164
165 /**
166 * Flushes the buffer and checks to see if the there has been an error in the printstream.
167 *
168 * @return True if the print stream has encountered an error
169 * either on the underlying output stream or during a format
170 * conversion.
171 */
172 boolean checkError();
173
174 /**
175 * Get latest exception.
176 * <p>
177 * NOTE: This does not return exception which are caught by underlying writer (PrintWriter) or stream.
178 * If you are using this method then consider using a Writer class that throws exceptions.
179 *
180 * @return the latest IOException encountered in the print stream either on the underlying
181 * output stream or during a format conversion.
182 */
183 IOException getException();
184
185 /**
186 * Set the error back to null to be able to check for the next error
187 * using {@link ICSVWriter#checkError()}.
188 */
189 void resetError();
190
191 /**
192 * Sets the result service.
193 * @param resultService The ResultSetHelper
194 */
195 void setResultService(ResultSetHelper resultService);
196
197 /**
198 * Flushes the writer without throwing any exceptions.
199 */
200 default void flushQuietly() {
201 try {
202 flush();
203 } catch (IOException e) {
204 // catch exception and ignore.
205 }
206 }
207 }