View Javadoc

1   /*
2    * Copyright (c) 2004, RV Test Team
3    * All rights reserved.
4    *
5    * Redistribution and use in source and binary forms, with or without
6    * modification, are permitted provided that the following conditions are met:
7    *
8    * Redistributions of source code must retain the above copyright notice, this
9    * list of conditions and the following disclaimer.
10   *
11   * Redistributions in binary form must reproduce the above copyright notice,
12   * this list of conditions and the following disclaimer in the documentation
13   * and/or other materials provided with the distribution.
14   *
15   * Neither the name of the "RV Test Team" nor the names of its contributors may
16   * be used to endorse or promote products derived from this software without
17   * specific prior written permission.
18   *
19   * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
20   * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21   * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22   * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
23   * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
24   * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
25   * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
26   * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
27   * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
28   * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
29   * THE POSSIBILITY OF SUCH DAMAGE.
30   *
31   */
32  //Created on Oct 6, 2004
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 }