1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33 package com.reuters.msgtest.load.output.csv;
34
35 import java.io.*;
36
37
38 /***
39 * Print values as a comma separated list.
40 * More information about this class is available from <a target="_top" href=
41 * "http://ostermiller.org/utils/CSVLexer.html">ostermiller.org</a>.
42 * This interface is designed to be set of general methods that all
43 * CSV printers should implement.
44 *
45 * @author Stephen Ostermiller http://ostermiller.org/contact.pl?regarding=Java+Utilities
46 * @author Pierre Dittgen <pierre dot dittgen at pass-tech dot fr>
47 * @since ostermillerutils 1.00.00
48 */
49 public interface CSVPrint {
50 /***
51 * Change this printer so that it uses a new delimiter.
52 *
53 * @param newDelimiter The new delimiter character to use.
54 * @throws BadDelimiterException if the character cannot be used as a delimiter.
55 *
56 * @author Pierre Dittgen <pierre dot dittgen at pass-tech dot fr>
57 * @since ostermillerutils 1.02.18
58 */
59 public void changeDelimiter(char newDelimiter) throws BadDelimeterException;
60
61 /***
62 * Change this printer so that it uses a new character for quoting.
63 *
64 * @param newQuote The new character to use for quoting.
65 * @throws BadQuoteException if the character cannot be used as a quote.
66 *
67 * @author Pierre Dittgen <pierre dot dittgen at pass-tech dot fr>
68 * @since ostermillerutils 1.02.18
69 */
70 public void changeQuote(char newQuote) throws BadQuoteException;
71
72 /***
73 * Set flushing behavior. Iff set, a flush command
74 * will be issued to any underlying stream after each
75 * print or write command.
76 *
77 * @param autoFlush should auto flushing be enabled.
78 *
79 * @since ostermillerutils 1.02.26
80 */
81 public void setAutoFlush(boolean autoFlush);
82
83 /***
84 * Flush the stream if it's not closed and check its error state.
85 * Errors are cumulative; once the stream encounters an error,
86 * this routine will return true on all successive calls.
87 *
88 * @return True if the print stream has encountered an error,
89 * either on the underlying output stream or during a format conversion.
90 *
91 * @since ostermillerutils 1.02.26
92 */
93 public boolean checkError();
94
95 /***
96 * Print the string as the last value on the line. The value
97 * will be quoted if needed. If value is null, an empty value is printed.
98 * <p>
99 * This method never throws an I/O exception. The client may inquire as to whether
100 * any errors have occurred by invoking checkError(). If an I/O Exception is
101 * desired, the client should use the corresponding writeln method.
102 *
103 * @param value value to be outputted.
104 *
105 * @since ostermillerutils 1.00.00
106 */
107 public void println(String value);
108
109 /***
110 * Print the string as the last value on the line. The value
111 * will be quoted if needed. If value is null, an empty value is printed.
112 *
113 * @param value value to be outputted.
114 * @throws IOException if an error occurs while writing.
115 *
116 * @since ostermillerutils 1.02.26
117 */
118 public void writeln(String value) throws IOException;
119
120 /***
121 * Output a blank line.
122 * <p>
123 * This method never throws an I/O exception. The client may inquire as to whether
124 * any errors have occurred by invoking checkError(). If an I/O Exception is
125 * desired, the client should use the corresponding writeln method.
126 *
127 * @since ostermillerutils 1.00.00
128 */
129 public void println();
130
131 /***
132 * Output a blank line.
133 *
134 * @throws IOException if an error occurs while writing.
135 *
136 * @since ostermillerutils 1.02.26
137 */
138 public void writeln() throws IOException;
139
140 /***
141 * Print a single line of comma separated values.
142 * The values will be quoted if needed. Quotes and
143 * and other characters that need it will be escaped.
144 * <p>
145 * This method never throws an I/O exception. The client may inquire as to whether
146 * any errors have occurred by invoking checkError(). If an I/O Exception is
147 * desired, the client should use the corresponding writeln method.
148 *
149 * @param values values to be outputted.
150 *
151 * @since ostermillerutils 1.00.00
152 */
153 public void println(String[] values);
154
155 /***
156 * Print a single line of comma separated values.
157 * The values will be quoted if needed. Quotes and
158 * and other characters that need it will be escaped.
159 *
160 * @param values values to be outputted.
161 * @throws IOException if an error occurs while writing.
162 *
163 * @since ostermillerutils 1.02.26
164 */
165 public void writeln(String[] values) throws IOException;
166
167 /***
168 * Print several lines of comma separated values.
169 * The values will be quoted if needed. Quotes and
170 * newLine characters will be escaped.
171 * <p>
172 * This method never throws an I/O exception. The client may inquire as to whether
173 * any errors have occurred by invoking checkError(). If an I/O Exception is
174 * desired, the client should use the corresponding writeln method.
175 *
176 * @param values values to be outputted.
177 *
178 * @since ostermillerutils 1.00.00
179 */
180 public void println(String[][] values);
181
182 /***
183 * Print several lines of comma separated values.
184 * The values will be quoted if needed. Quotes and
185 * newLine characters will be escaped.
186 *
187 * @param values values to be outputted.
188 * @throws IOException if an error occurs while writing.
189 *
190 * @since ostermillerutils 1.02.26
191 */
192 public void writeln(String[][] values) throws IOException;
193
194 /***
195 * If the CSV format supports comments, write the comment
196 * to the file on its own line, otherwise, start a new line.
197 * <p>
198 * This method never throws an I/O exception. The client may inquire as to whether
199 * any errors have occurred by invoking checkError(). If an I/O Exception is
200 * desired, the client should use the corresponding writelnComment method.
201 *
202 * @param comment the comment to output.
203 *
204 * @since ostermillerutils 1.00.00
205 */
206 public void printlnComment(String comment);
207
208 /***
209 * If the CSV format supports comments, write the comment
210 * to the file on its own line, otherwise, start a new line.
211 *
212 * @param comment the comment to output.
213 * @throws IOException if an error occurs while writing.
214 *
215 * @since ostermillerutils 1.02.26
216 */
217 public void writelnComment(String comment) throws IOException;
218
219 /***
220 * Print the string as the next value on the line. The value
221 * will be quoted if needed.
222 * <p>
223 * This method never throws an I/O exception. The client may inquire as to whether
224 * any errors have occurred by invoking checkError(). If an I/O Exception is
225 * desired, the client should use the corresponding println method.
226 *
227 * @param value value to be outputted.
228 *
229 * @since ostermillerutils 1.00.00
230 */
231 public void print(String value);
232
233 /***
234 * Print the string as the next value on the line. The value
235 * will be quoted if needed.
236 *
237 * @param value value to be outputted.
238 * @throws IOException if an error occurs while writing.
239 *
240 * @since ostermillerutils 1.02.26
241 */
242 public void write(String value) throws IOException;
243
244 /***
245 * Flush any data written out to underlying streams.
246 *
247 * @since ostermillerutils 1.02.26
248 */
249 public void flush() throws IOException;
250
251 /***
252 * Close any underlying streams.
253 *
254 * @since ostermillerutils 1.02.26
255 */
256 public void close() throws IOException;
257
258 /***
259 * Print multiple delimited values values.
260 * The values will be quoted if needed. Quotes and
261 * and other characters that need it will be escaped.
262 * <p>
263 * This method never throws an I/O exception. The client may inquire as to whether
264 * any errors have occurred by invoking checkError(). If an I/O Exception is
265 * desired, the client should use the corresponding write method.
266 *
267 * @param values values to be outputted.
268 *
269 * @since ostermillerutils 1.02.26
270 */
271 public void print(String[] values);
272
273 /***
274 * Print multiple delimited values values.
275 * The values will be quoted if needed. Quotes and
276 * and other characters that need it will be escaped.
277 *
278 * @param values values to be outputted.
279 * @throws IOException if an error occurs while writing.
280 *
281 * @since ostermillerutils 1.02.26
282 */
283 public void write(String[] values) throws IOException;
284
285 /***
286 * Set whether values printers should always be quoted, or
287 * whether the printer may, at its discretion, omit quotes
288 * around the value.
289 *
290 * @param alwaysQuote true if quotes should be used even when not strictly needed.
291 *
292 * @since ostermillerutils 1.02.26
293 */
294 public void setAlwaysQuote(boolean alwaysQuote);
295 }