KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > io > PrintWriter


1 /*
2  * @(#)PrintWriter.java 1.37 04/07/16
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */

7
8 package java.io;
9
10 import java.util.Formatter JavaDoc;
11 import java.util.Locale JavaDoc;
12
13 /**
14  * Print formatted representations of objects to a text-output stream. This
15  * class implements all of the <tt>print</tt> methods found in {@link
16  * PrintStream}. It does not contain methods for writing raw bytes, for which
17  * a program should use unencoded byte streams.
18  *
19  * <p> Unlike the {@link PrintStream} class, if automatic flushing is enabled
20  * it will be done only when one of the <tt>println</tt>, <tt>printf</tt>, or
21  * <tt>format</tt> methods is invoked, rather than whenever a newline character
22  * happens to be output. These methods use the platform's own notion of line
23  * separator rather than the newline character.
24  *
25  * <p> Methods in this class never throw I/O exceptions, although some of its
26  * constructors may. The client may inquire as to whether any errors have
27  * occurred by invoking {@link #checkError checkError()}.
28  *
29  * @version 1.37, 07/16/04
30  * @author Frank Yellin
31  * @author Mark Reinhold
32  * @since JDK1.1
33  */

34
35 public class PrintWriter extends Writer JavaDoc {
36
37     /**
38      * The underlying character-output stream of this
39      * <code>PrintWriter</code>.
40      *
41      * @since 1.2
42      */

43     protected Writer JavaDoc out;
44
45     private boolean autoFlush = false;
46     private boolean trouble = false;
47     private Formatter JavaDoc formatter;
48
49     /**
50      * Line separator string. This is the value of the line.separator
51      * property at the moment that the stream was created.
52      */

53     private String JavaDoc lineSeparator;
54
55     /**
56      * Create a new PrintWriter, without automatic line flushing.
57      *
58      * @param out A character-output stream
59      */

60     public PrintWriter (Writer JavaDoc out) {
61     this(out, false);
62     }
63
64     /**
65      * Create a new PrintWriter.
66      *
67      * @param out A character-output stream
68      * @param autoFlush A boolean; if true, the <tt>println</tt>,
69      * <tt>printf</tt>, or <tt>format</tt> methods will
70      * flush the output buffer
71      */

72     public PrintWriter(Writer JavaDoc out,
73                boolean autoFlush) {
74     super(out);
75     this.out = out;
76     this.autoFlush = autoFlush;
77     lineSeparator = (String JavaDoc) java.security.AccessController.doPrivileged(
78                new sun.security.action.GetPropertyAction("line.separator"));
79     }
80
81     /**
82      * Create a new PrintWriter, without automatic line flushing, from an
83      * existing OutputStream. This convenience constructor creates the
84      * necessary intermediate OutputStreamWriter, which will convert characters
85      * into bytes using the default character encoding.
86      *
87      * @param out An output stream
88      *
89      * @see java.io.OutputStreamWriter#OutputStreamWriter(java.io.OutputStream)
90      */

91     public PrintWriter(OutputStream JavaDoc out) {
92     this(out, false);
93     }
94
95     /**
96      * Create a new PrintWriter from an existing OutputStream. This
97      * convenience constructor creates the necessary intermediate
98      * OutputStreamWriter, which will convert characters into bytes using the
99      * default character encoding.
100      *
101      * @param out An output stream
102      * @param autoFlush A boolean; if true, the <tt>println</tt>,
103      * <tt>printf</tt>, or <tt>format</tt> methods will
104      * flush the output buffer
105      *
106      * @see java.io.OutputStreamWriter#OutputStreamWriter(java.io.OutputStream)
107      */

108     public PrintWriter(OutputStream JavaDoc out, boolean autoFlush) {
109     this(new BufferedWriter JavaDoc(new OutputStreamWriter JavaDoc(out)), autoFlush);
110     }
111
112     /**
113      * Creates a new PrintWriter, without automatic line flushing, with the
114      * specified file name. This convenience constructor creates the necessary
115      * intermediate {@link java.io.OutputStreamWriter OutputStreamWriter},
116      * which will encode characters using the {@linkplain
117      * java.nio.charset.Charset#defaultCharset default charset} for this
118      * instance of the Java virtual machine.
119      *
120      * @param fileName
121      * The name of the file to use as the destination of this writer.
122      * If the file exists then it will be truncated to zero size;
123      * otherwise, a new file will be created. The output will be
124      * written to the file and is buffered.
125      *
126      * @throws FileNotFoundException
127      * If the given string does not denote an existing, writable
128      * regular file and a new regular file of that name cannot be
129      * created, or if some other error occurs while opening or
130      * creating the file
131      *
132      * @throws SecurityException
133      * If a security manager is present and {@link
134      * SecurityManager#checkWrite checkWrite(fileName)} denies write
135      * access to the file
136      *
137      * @since 1.5
138      */

139     public PrintWriter(String JavaDoc fileName) throws FileNotFoundException JavaDoc {
140     this(new BufferedWriter JavaDoc(new OutputStreamWriter JavaDoc(new FileOutputStream JavaDoc(fileName))),
141          false);
142     }
143
144     /**
145      * Creates a new PrintWriter, without automatic line flushing, with the
146      * specified file name and charset. This convenience constructor creates
147      * the necessary intermediate {@link java.io.OutputStreamWriter
148      * OutputStreamWriter}, which will encode characters using the provided
149      * charset.
150      *
151      * @param fileName
152      * The name of the file to use as the destination of this writer.
153      * If the file exists then it will be truncated to zero size;
154      * otherwise, a new file will be created. The output will be
155      * written to the file and is buffered.
156      *
157      * @param csn
158      * The name of a supported {@linkplain java.nio.charset.Charset
159      * charset}
160      *
161      * @throws FileNotFoundException
162      * If the given string does not denote an existing, writable
163      * regular file and a new regular file of that name cannot be
164      * created, or if some other error occurs while opening or
165      * creating the file
166      *
167      * @throws SecurityException
168      * If a security manager is present and {@link
169      * SecurityManager#checkWrite checkWrite(fileName)} denies write
170      * access to the file
171      *
172      * @throws UnsupportedEncodingException
173      * If the named charset is not supported
174      *
175      * @since 1.5
176      */

177     public PrintWriter(String JavaDoc fileName, String JavaDoc csn)
178     throws FileNotFoundException JavaDoc, UnsupportedEncodingException JavaDoc
179     {
180     this(new BufferedWriter JavaDoc(new OutputStreamWriter JavaDoc(new FileOutputStream JavaDoc(fileName), csn)),
181          false);
182     }
183
184     /**
185      * Creates a new PrintWriter, without automatic line flushing, with the
186      * specified file. This convenience constructor creates the necessary
187      * intermediate {@link java.io.OutputStreamWriter OutputStreamWriter},
188      * which will encode characters using the {@linkplain
189      * java.nio.charset.Charset#defaultCharset default charset} for this
190      * instance of the Java virtual machine.
191      *
192      * @param file
193      * The file to use as the destination of this writer. If the file
194      * exists then it will be truncated to zero size; otherwise, a new
195      * file will be created. The output will be written to the file
196      * and is buffered.
197      *
198      * @throws FileNotFoundException
199      * If the given file object does not denote an existing, writable
200      * regular file and a new regular file of that name cannot be
201      * created, or if some other error occurs while opening or
202      * creating the file
203      *
204      * @throws SecurityException
205      * If a security manager is present and {@link
206      * SecurityManager#checkWrite checkWrite(file.getPath())}
207      * denies write access to the file
208      *
209      * @since 1.5
210      */

211     public PrintWriter(File JavaDoc file) throws FileNotFoundException JavaDoc {
212     this(new BufferedWriter JavaDoc(new OutputStreamWriter JavaDoc(new FileOutputStream JavaDoc(file))),
213          false);
214     }
215
216     /**
217      * Creates a new PrintWriter, without automatic line flushing, with the
218      * specified file and charset. This convenience constructor creates the
219      * necessary intermediate {@link java.io.OutputStreamWriter
220      * OutputStreamWriter}, which will encode characters using the provided
221      * charset.
222      *
223      * @param file
224      * The file to use as the destination of this writer. If the file
225      * exists then it will be truncated to zero size; otherwise, a new
226      * file will be created. The output will be written to the file
227      * and is buffered.
228      *
229      * @param csn
230      * The name of a supported {@linkplain java.nio.charset.Charset
231      * charset}
232      *
233      * @throws FileNotFoundException
234      * If the given file object does not denote an existing, writable
235      * regular file and a new regular file of that name cannot be
236      * created, or if some other error occurs while opening or
237      * creating the file
238      *
239      * @throws SecurityException
240      * If a security manager is present and {@link
241      * SecurityManager#checkWrite checkWrite(file.getPath())}
242      * denies write access to the file
243      *
244      * @throws UnsupportedEncodingException
245      * If the named charset is not supported
246      *
247      * @since 1.5
248      */

249     public PrintWriter(File JavaDoc file, String JavaDoc csn)
250     throws FileNotFoundException JavaDoc, UnsupportedEncodingException JavaDoc
251     {
252     this(new BufferedWriter JavaDoc(new OutputStreamWriter JavaDoc(new FileOutputStream JavaDoc(file), csn)),
253          false);
254     }
255
256     /** Check to make sure that the stream has not been closed */
257     private void ensureOpen() throws IOException JavaDoc {
258     if (out == null)
259         throw new IOException JavaDoc("Stream closed");
260     }
261
262     /**
263      * Flush the stream.
264      * @see #checkError()
265      */

266     public void flush() {
267     try {
268         synchronized (lock) {
269         ensureOpen();
270         out.flush();
271         }
272     }
273     catch (IOException JavaDoc x) {
274         trouble = true;
275     }
276     }
277
278     /**
279      * Close the stream.
280      * @see #checkError()
281      */

282     public void close() {
283     try {
284         synchronized (lock) {
285         if (out == null)
286             return;
287         out.close();
288         out = null;
289         }
290     }
291     catch (IOException JavaDoc x) {
292         trouble = true;
293     }
294     }
295
296     /**
297      * Flush the stream if it's not closed and check its error state.
298      * Errors are cumulative; once the stream encounters an error, this
299      * routine will return true on all successive calls.
300      *
301      * @return True if the print stream has encountered an error, either on the
302      * underlying output stream or during a format conversion.
303      */

304     public boolean checkError() {
305     if (out != null)
306         flush();
307     return trouble;
308     }
309
310     /** Indicate that an error has occurred. */
311     protected void setError() {
312     trouble = true;
313     try {
314         throw new IOException JavaDoc();
315     } catch (IOException JavaDoc x) {
316     }
317     }
318
319
320     /*
321      * Exception-catching, synchronized output operations,
322      * which also implement the write() methods of Writer
323      */

324
325     /**
326      * Write a single character.
327      * @param c int specifying a character to be written.
328      */

329     public void write(int c) {
330     try {
331         synchronized (lock) {
332         ensureOpen();
333         out.write(c);
334         }
335     }
336     catch (InterruptedIOException JavaDoc x) {
337         Thread.currentThread().interrupt();
338     }
339     catch (IOException JavaDoc x) {
340         trouble = true;
341     }
342     }
343
344     /**
345      * Write A Portion of an array of characters.
346      * @param buf Array of characters
347      * @param off Offset from which to start writing characters
348      * @param len Number of characters to write
349      */

350     public void write(char buf[], int off, int len) {
351     try {
352         synchronized (lock) {
353         ensureOpen();
354         out.write(buf, off, len);
355         }
356     }
357     catch (InterruptedIOException JavaDoc x) {
358         Thread.currentThread().interrupt();
359     }
360     catch (IOException JavaDoc x) {
361         trouble = true;
362     }
363     }
364
365     /**
366      * Write an array of characters. This method cannot be inherited from the
367      * Writer class because it must suppress I/O exceptions.
368      * @param buf Array of characters to be written
369      */

370     public void write(char buf[]) {
371     write(buf, 0, buf.length);
372     }
373
374     /**
375      * Write a portion of a string.
376      * @param s A String
377      * @param off Offset from which to start writing characters
378      * @param len Number of characters to write
379      */

380     public void write(String JavaDoc s, int off, int len) {
381     try {
382         synchronized (lock) {
383         ensureOpen();
384         out.write(s, off, len);
385         }
386     }
387     catch (InterruptedIOException JavaDoc x) {
388         Thread.currentThread().interrupt();
389     }
390     catch (IOException JavaDoc x) {
391         trouble = true;
392     }
393     }
394
395     /**
396      * Write a string. This method cannot be inherited from the Writer class
397      * because it must suppress I/O exceptions.
398      * @param s String to be written
399      */

400     public void write(String JavaDoc s) {
401     write(s, 0, s.length());
402     }
403
404     private void newLine() {
405     try {
406         synchronized (lock) {
407         ensureOpen();
408         out.write(lineSeparator);
409         if (autoFlush)
410             out.flush();
411         }
412     }
413     catch (InterruptedIOException JavaDoc x) {
414         Thread.currentThread().interrupt();
415     }
416     catch (IOException JavaDoc x) {
417         trouble = true;
418     }
419     }
420
421
422     /* Methods that do not terminate lines */
423
424     /**
425      * Print a boolean value. The string produced by <code>{@link
426      * java.lang.String#valueOf(boolean)}</code> is translated into bytes
427      * according to the platform's default character encoding, and these bytes
428      * are written in exactly the manner of the <code>{@link
429      * #write(int)}</code> method.
430      *
431      * @param b The <code>boolean</code> to be printed
432      */

433     public void print(boolean b) {
434     write(b ? "true" : "false");
435     }
436
437     /**
438      * Print a character. The character is translated into one or more bytes
439      * according to the platform's default character encoding, and these bytes
440      * are written in exactly the manner of the <code>{@link
441      * #write(int)}</code> method.
442      *
443      * @param c The <code>char</code> to be printed
444      */

445     public void print(char c) {
446     write(c);
447     }
448
449     /**
450      * Print an integer. The string produced by <code>{@link
451      * java.lang.String#valueOf(int)}</code> is translated into bytes according
452      * to the platform's default character encoding, and these bytes are
453      * written in exactly the manner of the <code>{@link #write(int)}</code>
454      * method.
455      *
456      * @param i The <code>int</code> to be printed
457      * @see java.lang.Integer#toString(int)
458      */

459     public void print(int i) {
460     write(String.valueOf(i));
461     }
462
463     /**
464      * Print a long integer. The string produced by <code>{@link
465      * java.lang.String#valueOf(long)}</code> is translated into bytes
466      * according to the platform's default character encoding, and these bytes
467      * are written in exactly the manner of the <code>{@link #write(int)}</code>
468      * method.
469      *
470      * @param l The <code>long</code> to be printed
471      * @see java.lang.Long#toString(long)
472      */

473     public void print(long l) {
474     write(String.valueOf(l));
475     }
476
477     /**
478      * Print a floating-point number. The string produced by <code>{@link
479      * java.lang.String#valueOf(float)}</code> is translated into bytes
480      * according to the platform's default character encoding, and these bytes
481      * are written in exactly the manner of the <code>{@link #write(int)}</code>
482      * method.
483      *
484      * @param f The <code>float</code> to be printed
485      * @see java.lang.Float#toString(float)
486      */

487     public void print(float f) {
488     write(String.valueOf(f));
489     }
490
491     /**
492      * Print a double-precision floating-point number. The string produced by
493      * <code>{@link java.lang.String#valueOf(double)}</code> is translated into
494      * bytes according to the platform's default character encoding, and these
495      * bytes are written in exactly the manner of the <code>{@link
496      * #write(int)}</code> method.
497      *
498      * @param d The <code>double</code> to be printed
499      * @see java.lang.Double#toString(double)
500      */

501     public void print(double d) {
502     write(String.valueOf(d));
503     }
504
505     /**
506      * Print an array of characters. The characters are converted into bytes
507      * according to the platform's default character encoding, and these bytes
508      * are written in exactly the manner of the <code>{@link #write(int)}</code>
509      * method.
510      *
511      * @param s The array of chars to be printed
512      *
513      * @throws NullPointerException If <code>s</code> is <code>null</code>
514      */

515     public void print(char s[]) {
516     write(s);
517     }
518
519     /**
520      * Print a string. If the argument is <code>null</code> then the string
521      * <code>"null"</code> is printed. Otherwise, the string's characters are
522      * converted into bytes according to the platform's default character
523      * encoding, and these bytes are written in exactly the manner of the
524      * <code>{@link #write(int)}</code> method.
525      *
526      * @param s The <code>String</code> to be printed
527      */

528     public void print(String JavaDoc s) {
529     if (s == null) {
530         s = "null";
531     }
532     write(s);
533     }
534
535     /**
536      * Print an object. The string produced by the <code>{@link
537      * java.lang.String#valueOf(Object)}</code> method is translated into bytes
538      * according to the platform's default character encoding, and these bytes
539      * are written in exactly the manner of the <code>{@link #write(int)}</code>
540      * method.
541      *
542      * @param obj The <code>Object</code> to be printed
543      * @see java.lang.Object#toString()
544      */

545     public void print(Object JavaDoc obj) {
546     write(String.valueOf(obj));
547     }
548
549
550     /* Methods that do terminate lines */
551
552     /**
553      * Terminate the current line by writing the line separator string. The
554      * line separator string is defined by the system property
555      * <code>line.separator</code>, and is not necessarily a single newline
556      * character (<code>'\n'</code>).
557      */

558     public void println() {
559     newLine();
560     }
561
562     /**
563      * Print a boolean value and then terminate the line. This method behaves
564      * as though it invokes <code>{@link #print(boolean)}</code> and then
565      * <code>{@link #println()}</code>.
566      *
567      * @param x the <code>boolean</code> value to be printed
568      */

569     public void println(boolean x) {
570     synchronized (lock) {
571         print(x);
572         println();
573     }
574     }
575
576     /**
577      * Print a character and then terminate the line. This method behaves as
578      * though it invokes <code>{@link #print(char)}</code> and then <code>{@link
579      * #println()}</code>.
580      *
581      * @param x the <code>char</code> value to be printed
582      */

583     public void println(char x) {
584     synchronized (lock) {
585         print(x);
586         println();
587     }
588     }
589
590     /**
591      * Print an integer and then terminate the line. This method behaves as
592      * though it invokes <code>{@link #print(int)}</code> and then <code>{@link
593      * #println()}</code>.
594      *
595      * @param x the <code>int</code> value to be printed
596      */

597     public void println(int x) {
598     synchronized (lock) {
599         print(x);
600         println();
601     }
602     }
603
604     /**
605      * Print a long integer and then terminate the line. This method behaves
606      * as though it invokes <code>{@link #print(long)}</code> and then
607      * <code>{@link #println()}</code>.
608      *
609      * @param x the <code>long</code> value to be printed
610      */

611     public void println(long x) {
612     synchronized (lock) {
613         print(x);
614         println();
615     }
616     }
617
618     /**
619      * Print a floating-point number and then terminate the line. This method
620      * behaves as though it invokes <code>{@link #print(float)}</code> and then
621      * <code>{@link #println()}</code>.
622      *
623      * @param x the <code>float</code> value to be printed
624      */

625     public void println(float x) {
626     synchronized (lock) {
627         print(x);
628         println();
629     }
630     }
631
632     /**
633      * Print a double-precision floating-point number and then terminate the
634      * line. This method behaves as though it invokes <code>{@link
635      * #print(double)}</code> and then <code>{@link #println()}</code>.
636      *
637      * @param x the <code>double</code> value to be printed
638      */

639     public void println(double x) {
640     synchronized (lock) {
641         print(x);
642         println();
643     }
644     }
645
646     /**
647      * Print an array of characters and then terminate the line. This method
648      * behaves as though it invokes <code>{@link #print(char[])}</code> and then
649      * <code>{@link #println()}</code>.
650      *
651      * @param x the array of <code>char</code> values to be printed
652      */

653     public void println(char x[]) {
654     synchronized (lock) {
655         print(x);
656         println();
657     }
658     }
659
660     /**
661      * Print a String and then terminate the line. This method behaves as
662      * though it invokes <code>{@link #print(String)}</code> and then
663      * <code>{@link #println()}</code>.
664      *
665      * @param x the <code>String</code> value to be printed
666      */

667     public void println(String JavaDoc x) {
668     synchronized (lock) {
669         print(x);
670         println();
671     }
672     }
673
674     /**
675      * Print an Object and then terminate the line. This method behaves as
676      * though it invokes <code>{@link #print(Object)}</code> and then
677      * <code>{@link #println()}</code>.
678      *
679      * @param x the <code>Object</code> value to be printed
680      */

681     public void println(Object JavaDoc x) {
682     synchronized (lock) {
683         print(x);
684         println();
685     }
686     }
687
688     /**
689      * A convenience method to write a formatted string to this writer using
690      * the specified format string and arguments. If automatic flushing is
691      * enabled, calls to this method will flush the output buffer.
692      *
693      * <p> An invocation of this method of the form <tt>out.printf(format,
694      * args)</tt> behaves in exactly the same way as the invocation
695      *
696      * <pre>
697      * out.format(format, args) </pre>
698      *
699      * @param format
700      * A format string as described in <a
701      * HREF="../util/Formatter.html#syntax">Format string syntax</a>.
702      *
703      * @param args
704      * Arguments referenced by the format specifiers in the format
705      * string. If there are more arguments than format specifiers, the
706      * extra arguments are ignored. The number of arguments is
707      * variable and may be zero. The maximum number of arguments is
708      * limited by the maximum dimension of a Java array as defined by
709      * the <a HREF="http://java.sun.com/docs/books/vmspec/">Java
710      * Virtual Machine Specification</a>. The behaviour on a
711      * <tt>null</tt> argument depends on the <a
712      * HREF="../util/Formatter.html#syntax">conversion</a>.
713      *
714      * @throws IllegalFormatException
715      * If a format string contains an illegal syntax, a format
716      * specifier that is incompatible with the given arguments,
717      * insufficient arguments given the format string, or other
718      * illegal conditions. For specification of all possible
719      * formatting errors, see the <a
720      * HREF="../util/Formatter.html#detail">Details</a> section of the
721      * formatter class specification.
722      *
723      * @throws NullPointerException
724      * If the <tt>format</tt> is <tt>null</tt>
725      *
726      * @return This writer
727      *
728      * @since 1.5
729      */

730     public PrintWriter JavaDoc printf(String JavaDoc format, Object JavaDoc ... args) {
731     return format(format, args);
732     }
733
734     /**
735      * A convenience method to write a formatted string to this writer using
736      * the specified format string and arguments. If automatic flushing is
737      * enabled, calls to this method will flush the output buffer.
738      *
739      * <p> An invocation of this method of the form <tt>out.printf(l, format,
740      * args)</tt> behaves in exactly the same way as the invocation
741      *
742      * <pre>
743      * out.format(l, format, args) </pre>
744      *
745      * @param l
746      * The {@linkplain java.util.Locale locale} to apply during
747      * formatting. If <tt>l</tt> is <tt>null</tt> then no localization
748      * is applied.
749      *
750      * @param format
751      * A format string as described in <a
752      * HREF="../util/Formatter.html#syntax">Format string syntax</a>.
753      *
754      * @param args
755      * Arguments referenced by the format specifiers in the format
756      * string. If there are more arguments than format specifiers, the
757      * extra arguments are ignored. The number of arguments is
758      * variable and may be zero. The maximum number of arguments is
759      * limited by the maximum dimension of a Java array as defined by
760      * the <a HREF="http://java.sun.com/docs/books/vmspec/">Java
761      * Virtual Machine Specification</a>. The behaviour on a
762      * <tt>null</tt> argument depends on the <a
763      * HREF="../util/Formatter.html#syntax">conversion</a>.
764      *
765      * @throws IllegalFormatException
766      * If a format string contains an illegal syntax, a format
767      * specifier that is incompatible with the given arguments,
768      * insufficient arguments given the format string, or other
769      * illegal conditions. For specification of all possible
770      * formatting errors, see the <a
771      * HREF="../util/Formatter.html#detail">Details</a> section of the
772      * formatter class specification.
773      *
774      * @throws NullPointerException
775      * If the <tt>format</tt> is <tt>null</tt>
776      *
777      * @return This writer
778      *
779      * @since 1.5
780      */

781     public PrintWriter JavaDoc printf(Locale JavaDoc l, String JavaDoc format, Object JavaDoc ... args) {
782     return format(l, format, args);
783     }
784
785     /**
786      * Writes a formatted string to this writer using the specified format
787      * string and arguments. If automatic flushing is enabled, calls to this
788      * method will flush the output buffer.
789      *
790      * <p> The locale always used is the one returned by {@link
791      * java.util.Locale#getDefault() Locale.getDefault()}, regardless of any
792      * previous invocations of other formatting methods on this object.
793      *
794      * @param format
795      * A format string as described in <a
796      * HREF="../util/Formatter.html#syntax">Format string syntax</a>.
797      *
798      * @param args
799      * Arguments referenced by the format specifiers in the format
800      * string. If there are more arguments than format specifiers, the
801      * extra arguments are ignored. The number of arguments is
802      * variable and may be zero. The maximum number of arguments is
803      * limited by the maximum dimension of a Java array as defined by
804      * the <a HREF="http://java.sun.com/docs/books/vmspec/">Java
805      * Virtual Machine Specification</a>. The behaviour on a
806      * <tt>null</tt> argument depends on the <a
807      * HREF="../util/Formatter.html#syntax">conversion</a>.
808      *
809      * @throws IllegalFormatException
810      * If a format string contains an illegal syntax, a format
811      * specifier that is incompatible with the given arguments,
812      * insufficient arguments given the format string, or other
813      * illegal conditions. For specification of all possible
814      * formatting errors, see the <a
815      * HREF="../util/Formatter.html#detail">Details</a> section of the
816      * Formatter class specification.
817      *
818      * @throws NullPointerException
819      * If the <tt>format</tt> is <tt>null</tt>
820      *
821      * @return This writer
822      *
823      * @since 1.5
824      */

825     public PrintWriter JavaDoc format(String JavaDoc format, Object JavaDoc ... args) {
826     try {
827         synchronized (lock) {
828         ensureOpen();
829         if ((formatter == null)
830             || (formatter.locale() != Locale.getDefault()))
831             formatter = new Formatter JavaDoc(this);
832         formatter.format(Locale.getDefault(), format, args);
833         if (autoFlush)
834             out.flush();
835         }
836     } catch (InterruptedIOException JavaDoc x) {
837         Thread.currentThread().interrupt();
838     } catch (IOException JavaDoc x) {
839         trouble = true;
840     }
841     return this;
842     }
843
844     /**
845      * Writes a formatted string to this writer using the specified format
846      * string and arguments. If automatic flushing is enabled, calls to this
847      * method will flush the output buffer.
848      *
849      * @param l
850      * The {@linkplain java.util.Locale locale} to apply during
851      * formatting. If <tt>l</tt> is <tt>null</tt> then no localization
852      * is applied.
853      *
854      * @param format
855      * A format string as described in <a
856      * HREF="../util/Formatter.html#syntax">Format string syntax</a>.
857      *
858      * @param args
859      * Arguments referenced by the format specifiers in the format
860      * string. If there are more arguments than format specifiers, the
861      * extra arguments are ignored. The number of arguments is
862      * variable and may be zero. The maximum number of arguments is
863      * limited by the maximum dimension of a Java array as defined by
864      * the <a HREF="http://java.sun.com/docs/books/vmspec/">Java
865      * Virtual Machine Specification</a>. The behaviour on a
866      * <tt>null</tt> argument depends on the <a
867      * HREF="../util/Formatter.html#syntax">conversion</a>.
868      *
869      * @throws IllegalFormatException
870      * If a format string contains an illegal syntax, a format
871      * specifier that is incompatible with the given arguments,
872      * insufficient arguments given the format string, or other
873      * illegal conditions. For specification of all possible
874      * formatting errors, see the <a
875      * HREF="../util/Formatter.html#detail">Details</a> section of the
876      * formatter class specification.
877      *
878      * @throws NullPointerException
879      * If the <tt>format</tt> is <tt>null</tt>
880      *
881      * @return This writer
882      *
883      * @since 1.5
884      */

885     public PrintWriter JavaDoc format(Locale JavaDoc l, String JavaDoc format, Object JavaDoc ... args) {
886     try {
887         synchronized (lock) {
888         ensureOpen();
889         if ((formatter == null) || (formatter.locale() != l))
890             formatter = new Formatter JavaDoc(this, l);
891         formatter.format(l, format, args);
892         if (autoFlush)
893             out.flush();
894         }
895     } catch (InterruptedIOException JavaDoc x) {
896         Thread.currentThread().interrupt();
897     } catch (IOException JavaDoc x) {
898         trouble = true;
899     }
900     return this;
901     }
902
903     /**
904      * Appends the specified character sequence to this writer.
905      *
906      * <p> An invocation of this method of the form <tt>out.append(csq)</tt>
907      * behaves in exactly the same way as the invocation
908      *
909      * <pre>
910      * out.write(csq.toString()) </pre>
911      *
912      * <p> Depending on the specification of <tt>toString</tt> for the
913      * character sequence <tt>csq</tt>, the entire sequence may not be
914      * appended. For instance, invoking the <tt>toString</tt> method of a
915      * character buffer will return a subsequence whose content depends upon
916      * the buffer's position and limit.
917      *
918      * @param csq
919      * The character sequence to append. If <tt>csq</tt> is
920      * <tt>null</tt>, then the four characters <tt>"null"</tt> are
921      * appended to this writer.
922      *
923      * @return This writer
924      *
925      * @since 1.5
926      */

927     public PrintWriter JavaDoc append(CharSequence JavaDoc csq) {
928     if (csq == null)
929         write("null");
930     else
931         write(csq.toString());
932         return this;
933     }
934
935     /**
936      * Appends a subsequence of the specified character sequence to this writer.
937      *
938      * <p> An invocation of this method of the form <tt>out.append(csq, start,
939      * end)</tt> when <tt>csq</tt> is not <tt>null</tt>, behaves in
940      * exactly the same way as the invocation
941      *
942      * <pre>
943      * out.write(csq.subSequence(start, end).toString()) </pre>
944      *
945      * @param csq
946      * The character sequence from which a subsequence will be
947      * appended. If <tt>csq</tt> is <tt>null</tt>, then characters
948      * will be appended as if <tt>csq</tt> contained the four
949      * characters <tt>"null"</tt>.
950      *
951      * @param start
952      * The index of the first character in the subsequence
953      *
954      * @param end
955      * The index of the character following the last character in the
956      * subsequence
957      *
958      * @return This writer
959      *
960      * @throws IndexOutOfBoundsException
961      * If <tt>start</tt> or <tt>end</tt> are negative, <tt>start</tt>
962      * is greater than <tt>end</tt>, or <tt>end</tt> is greater than
963      * <tt>csq.length()</tt>
964      *
965      * @since 1.5
966      */

967     public PrintWriter JavaDoc append(CharSequence JavaDoc csq, int start, int end) {
968     CharSequence JavaDoc cs = (csq == null ? "null" : csq);
969     write(cs.subSequence(start, end).toString());
970         return this;
971     }
972     
973     /**
974      * Appends the specified character to this writer.
975      *
976      * <p> An invocation of this method of the form <tt>out.append(c)</tt>
977      * behaves in exactly the same way as the invocation
978      *
979      * <pre>
980      * out.write(c) </pre>
981      *
982      * @param c
983      * The 16-bit character to append
984      *
985      * @return This writer
986      *
987      * @since 1.5
988      */

989     public PrintWriter JavaDoc append(char c) {
990     write(c);
991     return this;
992     }
993 }
994
Popular Tags