001: /*
002: * Write files in comma separated value format.
003: * Copyright (C) 2002-2004 Stephen Ostermiller
004: * http://ostermiller.org/contact.pl?regarding=Java+Utilities
005: * Copyright (C) 2003 Pierre Dittgen <pierre dot dittgen at pass-tech dot fr>
006: *
007: * This program is free software; you can redistribute it and/or modify
008: * it under the terms of the GNU General Public License as published by
009: * the Free Software Foundation; either version 2 of the License, or
010: * (at your option) any later version.
011: *
012: * This program is distributed in the hope that it will be useful,
013: * but WITHOUT ANY WARRANTY; without even the implied warranty of
014: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
015: * GNU General Public License for more details.
016: *
017: * See COPYING.TXT for details.
018: */
019:
020: package com.Ostermiller.util;
021:
022: import java.io.*;
023:
024: /**
025: * Print values as a comma separated list.
026: * More information about this class is available from <a target="_top" href=
027: * "http://ostermiller.org/utils/CSVLexer.html">ostermiller.org</a>.
028: * This interface is designed to be set of general methods that all
029: * CSV printers should implement.
030: *
031: * @author Stephen Ostermiller http://ostermiller.org/contact.pl?regarding=Java+Utilities
032: * @author Pierre Dittgen <pierre dot dittgen at pass-tech dot fr>
033: * @since ostermillerutils 1.00.00
034: */
035: public interface CSVPrint {
036:
037: /**
038: * Change this printer so that it uses a new delimiter.
039: *
040: * @param newDelimiter The new delimiter character to use.
041: * @throws BadDelimiterException if the character cannot be used as a delimiter.
042: *
043: * @author Pierre Dittgen <pierre dot dittgen at pass-tech dot fr>
044: * @since ostermillerutils 1.02.18
045: */
046: public void changeDelimiter(char newDelimiter)
047: throws BadDelimiterException;
048:
049: /**
050: * Change this printer so that it uses a new character for quoting.
051: *
052: * @param newQuote The new character to use for quoting.
053: * @throws BadQuoteException if the character cannot be used as a quote.
054: *
055: * @author Pierre Dittgen <pierre dot dittgen at pass-tech dot fr>
056: * @since ostermillerutils 1.02.18
057: */
058: public void changeQuote(char newQuote) throws BadQuoteException;
059:
060: /**
061: * Set flushing behavior. Iff set, a flush command
062: * will be issued to any underlying stream after each
063: * print or write command.
064: *
065: * @param autoFlush should auto flushing be enabled.
066: *
067: * @since ostermillerutils 1.02.26
068: */
069: public void setAutoFlush(boolean autoFlush);
070:
071: /**
072: * Flush the stream if it's not closed and check its error state.
073: * Errors are cumulative; once the stream encounters an error,
074: * this routine will return true on all successive calls.
075: *
076: * @return True if the print stream has encountered an error,
077: * either on the underlying output stream or during a format conversion.
078: *
079: * @since ostermillerutils 1.02.26
080: */
081: public boolean checkError();
082:
083: /**
084: * Print the string as the last value on the line. The value
085: * will be quoted if needed. If value is null, an empty value is printed.
086: * <p>
087: * This method never throws an I/O exception. The client may inquire as to whether
088: * any errors have occurred by invoking checkError(). If an I/O Exception is
089: * desired, the client should use the corresponding writeln method.
090: *
091: * @param value value to be outputted.
092: *
093: * @since ostermillerutils 1.00.00
094: */
095: public void println(String value);
096:
097: /**
098: * Print the string as the last value on the line. The value
099: * will be quoted if needed. If value is null, an empty value is printed.
100: *
101: * @param value value to be outputted.
102: * @throws IOException if an error occurs while writing.
103: *
104: * @since ostermillerutils 1.02.26
105: */
106: public void writeln(String value) throws IOException;
107:
108: /**
109: * Output a blank line.
110: * <p>
111: * This method never throws an I/O exception. The client may inquire as to whether
112: * any errors have occurred by invoking checkError(). If an I/O Exception is
113: * desired, the client should use the corresponding writeln method.
114: *
115: * @since ostermillerutils 1.00.00
116: */
117: public void println();
118:
119: /**
120: * Output a blank line.
121: *
122: * @throws IOException if an error occurs while writing.
123: *
124: * @since ostermillerutils 1.02.26
125: */
126: public void writeln() throws IOException;
127:
128: /**
129: * Print a single line of comma separated values.
130: * The values will be quoted if needed. Quotes and
131: * and other characters that need it will be escaped.
132: * <p>
133: * This method never throws an I/O exception. The client may inquire as to whether
134: * any errors have occurred by invoking checkError(). If an I/O Exception is
135: * desired, the client should use the corresponding writeln method.
136: *
137: * @param values values to be outputted.
138: *
139: * @since ostermillerutils 1.00.00
140: */
141: public void println(String[] values);
142:
143: /**
144: * Print a single line of comma separated values.
145: * The values will be quoted if needed. Quotes and
146: * and other characters that need it will be escaped.
147: *
148: * @param values values to be outputted.
149: * @throws IOException if an error occurs while writing.
150: *
151: * @since ostermillerutils 1.02.26
152: */
153: public void writeln(String[] values) throws IOException;
154:
155: /**
156: * Print several lines of comma separated values.
157: * The values will be quoted if needed. Quotes and
158: * newLine characters will be escaped.
159: * <p>
160: * This method never throws an I/O exception. The client may inquire as to whether
161: * any errors have occurred by invoking checkError(). If an I/O Exception is
162: * desired, the client should use the corresponding writeln method.
163: *
164: * @param values values to be outputted.
165: *
166: * @since ostermillerutils 1.00.00
167: */
168: public void println(String[][] values);
169:
170: /**
171: * Print several lines of comma separated values.
172: * The values will be quoted if needed. Quotes and
173: * newLine characters will be escaped.
174: *
175: * @param values values to be outputted.
176: * @throws IOException if an error occurs while writing.
177: *
178: * @since ostermillerutils 1.02.26
179: */
180: public void writeln(String[][] values) throws IOException;
181:
182: /**
183: * If the CSV format supports comments, write the comment
184: * to the file on its own line, otherwise, start a new line.
185: * <p>
186: * This method never throws an I/O exception. The client may inquire as to whether
187: * any errors have occurred by invoking checkError(). If an I/O Exception is
188: * desired, the client should use the corresponding writelnComment method.
189: *
190: * @param comment the comment to output.
191: *
192: * @since ostermillerutils 1.00.00
193: */
194: public void printlnComment(String comment);
195:
196: /**
197: * If the CSV format supports comments, write the comment
198: * to the file on its own line, otherwise, start a new line.
199: *
200: * @param comment the comment to output.
201: * @throws IOException if an error occurs while writing.
202: *
203: * @since ostermillerutils 1.02.26
204: */
205: public void writelnComment(String comment) throws IOException;
206:
207: /**
208: * Print the string as the next value on the line. The value
209: * will be quoted if needed.
210: * <p>
211: * This method never throws an I/O exception. The client may inquire as to whether
212: * any errors have occurred by invoking checkError(). If an I/O Exception is
213: * desired, the client should use the corresponding println method.
214: *
215: * @param value value to be outputted.
216: *
217: * @since ostermillerutils 1.00.00
218: */
219: public void print(String value);
220:
221: /**
222: * Print the string as the next value on the line. The value
223: * will be quoted if needed.
224: *
225: * @param value value to be outputted.
226: * @throws IOException if an error occurs while writing.
227: *
228: * @since ostermillerutils 1.02.26
229: */
230: public void write(String value) throws IOException;
231:
232: /**
233: * Flush any data written out to underlying streams.
234: * @throws IOException if an IO error occurs
235: *
236: * @since ostermillerutils 1.02.26
237: */
238: public void flush() throws IOException;
239:
240: /**
241: * Close any underlying streams.
242: * @throws IOException if an IO error occurs
243: *
244: * @since ostermillerutils 1.02.26
245: */
246: public void close() throws IOException;
247:
248: /**
249: * Print multiple delimited values values.
250: * The values will be quoted if needed. Quotes and
251: * and other characters that need it will be escaped.
252: * <p>
253: * This method never throws an I/O exception. The client may inquire as to whether
254: * any errors have occurred by invoking checkError(). If an I/O Exception is
255: * desired, the client should use the corresponding write method.
256: *
257: * @param values values to be outputted.
258: *
259: * @since ostermillerutils 1.02.26
260: */
261: public void print(String[] values);
262:
263: /**
264: * Print multiple delimited values values.
265: * The values will be quoted if needed. Quotes and
266: * and other characters that need it will be escaped.
267: *
268: * @param values values to be outputted.
269: * @throws IOException if an error occurs while writing.
270: *
271: * @since ostermillerutils 1.02.26
272: */
273: public void write(String[] values) throws IOException;
274:
275: /**
276: * Set whether values printers should always be quoted, or
277: * whether the printer may, at its discretion, omit quotes
278: * around the value.
279: *
280: * @param alwaysQuote true if quotes should be used even when not strictly needed.
281: *
282: * @since ostermillerutils 1.02.26
283: */
284: public void setAlwaysQuote(boolean alwaysQuote);
285: }
|