CSVPrint


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