1 /*
2 * Copyright (c) 1996, 2006, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.io;
27
28 import java.util.Formatter;
29 import java.util.Locale;
30
31 /**
32 * Prints formatted representations of objects to a text-output stream. This
33 * class implements all of the <tt>print</tt> methods found in {@link
34 * PrintStream}. It does not contain methods for writing raw bytes, for which
35 * a program should use unencoded byte streams.
36 *
37 * <p> Unlike the {@link PrintStream} class, if automatic flushing is enabled
38 * it will be done only when one of the <tt>println</tt>, <tt>printf</tt>, or
39 * <tt>format</tt> methods is invoked, rather than whenever a newline character
40 * happens to be output. These methods use the platform's own notion of line
41 * separator rather than the newline character.
42 *
43 * <p> Methods in this class never throw I/O exceptions, although some of its
44 * constructors may. The client may inquire as to whether any errors have
45 * occurred by invoking {@link #checkError checkError()}.
46 *
47 * @author Frank Yellin
48 * @author Mark Reinhold
49 * @since JDK1.1
50 */
51
52 public class PrintWriter extends Writer {
53
54 /**
55 * The underlying character-output stream of this
56 * <code>PrintWriter</code>.
57 *
58 * @since 1.2
59 */
60 protected Writer out;
61
62 private boolean autoFlush = false;
63 private boolean trouble = false;
64 private Formatter formatter;
65 private PrintStream psOut = null;
66
67 /**
68 * Line separator string. This is the value of the line.separator
69 * property at the moment that the stream was created.
70 */
71 private String lineSeparator;
72
73 /**
74 * Creates a new PrintWriter, without automatic line flushing.
75 *
76 * @param out A character-output stream
77 */
78 public PrintWriter (Writer out) {
79 this(out, false);
80 }
81
82 /**
83 * Creates a new PrintWriter.
84 *
85 * @param out A character-output stream
86 * @param autoFlush A boolean; if true, the <tt>println</tt>,
87 * <tt>printf</tt>, or <tt>format</tt> methods will
88 * flush the output buffer
89 */
90 public PrintWriter(Writer out,
91 boolean autoFlush) {
92 super(out);
93 this.out = out;
94 this.autoFlush = autoFlush;
95 lineSeparator = java.security.AccessController.doPrivileged(
96 new sun.security.action.GetPropertyAction("line.separator"));
97 }
98
99 /**
100 * Creates a new PrintWriter, without automatic line flushing, from an
101 * existing OutputStream. This convenience constructor creates the
102 * necessary intermediate OutputStreamWriter, which will convert characters
103 * into bytes using the default character encoding.
104 *
105 * @param out An output stream
106 *
107 * @see java.io.OutputStreamWriter#OutputStreamWriter(java.io.OutputStream)
108 */
109 public PrintWriter(OutputStream out) {
110 this(out, false);
111 }
112
113 /**
114 * Creates a new PrintWriter from an existing OutputStream. This
115 * convenience constructor creates the necessary intermediate
116 * OutputStreamWriter, which will convert characters into bytes using the
117 * default character encoding.
118 *
119 * @param out An output stream
120 * @param autoFlush A boolean; if true, the <tt>println</tt>,
121 * <tt>printf</tt>, or <tt>format</tt> methods will
122 * flush the output buffer
123 *
124 * @see java.io.OutputStreamWriter#OutputStreamWriter(java.io.OutputStream)
125 */
126 public PrintWriter(OutputStream out, boolean autoFlush) {
127 this(new BufferedWriter(new OutputStreamWriter(out)), autoFlush);
128
129 // save print stream for error propagation
130 if (out instanceof java.io.PrintStream) {
131 psOut = (PrintStream) out;
132 }
133 }
134
135 /**
136 * Creates a new PrintWriter, without automatic line flushing, with the
137 * specified file name. This convenience constructor creates the necessary
138 * intermediate {@link java.io.OutputStreamWriter OutputStreamWriter},
139 * which will encode characters using the {@linkplain
140 * java.nio.charset.Charset#defaultCharset() default charset} for this
141 * instance of the Java virtual machine.
142 *
143 * @param fileName
144 * The name of the file to use as the destination of this writer.
145 * If the file exists then it will be truncated to zero size;
146 * otherwise, a new file will be created. The output will be
147 * written to the file and is buffered.
148 *
149 * @throws FileNotFoundException
150 * If the given string does not denote an existing, writable
151 * regular file and a new regular file of that name cannot be
152 * created, or if some other error occurs while opening or
153 * creating the file
154 *
155 * @throws SecurityException
156 * If a security manager is present and {@link
157 * SecurityManager#checkWrite checkWrite(fileName)} denies write
158 * access to the file
159 *
160 * @since 1.5
161 */
162 public PrintWriter(String fileName) throws FileNotFoundException {
163 this(new BufferedWriter(new OutputStreamWriter(new FileOutputStream(fileName))),
164 false);
165 }
166
167 /**
168 * Creates a new PrintWriter, without automatic line flushing, with the
169 * specified file name and charset. This convenience constructor creates
170 * the necessary intermediate {@link java.io.OutputStreamWriter
171 * OutputStreamWriter}, which will encode characters using the provided
172 * charset.
173 *
174 * @param fileName
175 * The name of the file to use as the destination of this writer.
176 * If the file exists then it will be truncated to zero size;
177 * otherwise, a new file will be created. The output will be
178 * written to the file and is buffered.
179 *
180 * @param csn
181 * The name of a supported {@linkplain java.nio.charset.Charset
182 * charset}
183 *
184 * @throws FileNotFoundException
185 * If the given string does not denote an existing, writable
186 * regular file and a new regular file of that name cannot be
187 * created, or if some other error occurs while opening or
188 * creating the file
189 *
190 * @throws SecurityException
191 * If a security manager is present and {@link
192 * SecurityManager#checkWrite checkWrite(fileName)} denies write
193 * access to the file
194 *
195 * @throws UnsupportedEncodingException
196 * If the named charset is not supported
197 *
198 * @since 1.5
199 */
200 public PrintWriter(String fileName, String csn)
201 throws FileNotFoundException, UnsupportedEncodingException
202 {
203 this(new BufferedWriter(new OutputStreamWriter(new FileOutputStream(fileName), csn)),
204 false);
205 }
206
207 /**
208 * Creates a new PrintWriter, without automatic line flushing, with the
209 * specified file. This convenience constructor creates the necessary
210 * intermediate {@link java.io.OutputStreamWriter OutputStreamWriter},
211 * which will encode characters using the {@linkplain
212 * java.nio.charset.Charset#defaultCharset() default charset} for this
213 * instance of the Java virtual machine.
214 *
215 * @param file
216 * The file to use as the destination of this writer. If the file
217 * exists then it will be truncated to zero size; otherwise, a new
218 * file will be created. The output will be written to the file
219 * and is buffered.
220 *
221 * @throws FileNotFoundException
222 * If the given file object does not denote an existing, writable
223 * regular file and a new regular file of that name cannot be
224 * created, or if some other error occurs while opening or
225 * creating the file
226 *
227 * @throws SecurityException
228 * If a security manager is present and {@link
229 * SecurityManager#checkWrite checkWrite(file.getPath())}
230 * denies write access to the file
231 *
232 * @since 1.5
233 */
234 public PrintWriter(File file) throws FileNotFoundException {
235 this(new BufferedWriter(new OutputStreamWriter(new FileOutputStream(file))),
236 false);
237 }
238
239 /**
240 * Creates a new PrintWriter, without automatic line flushing, with the
241 * specified file and charset. This convenience constructor creates the
242 * necessary intermediate {@link java.io.OutputStreamWriter
243 * OutputStreamWriter}, which will encode characters using the provided
244 * charset.
245 *
246 * @param file
247 * The file to use as the destination of this writer. If the file
248 * exists then it will be truncated to zero size; otherwise, a new
249 * file will be created. The output will be written to the file
250 * and is buffered.
251 *
252 * @param csn
253 * The name of a supported {@linkplain java.nio.charset.Charset
254 * charset}
255 *
256 * @throws FileNotFoundException
257 * If the given file object does not denote an existing, writable
258 * regular file and a new regular file of that name cannot be
259 * created, or if some other error occurs while opening or
260 * creating the file
261 *
262 * @throws SecurityException
263 * If a security manager is present and {@link
264 * SecurityManager#checkWrite checkWrite(file.getPath())}
265 * denies write access to the file
266 *
267 * @throws UnsupportedEncodingException
268 * If the named charset is not supported
269 *
270 * @since 1.5
271 */
272 public PrintWriter(File file, String csn)
273 throws FileNotFoundException, UnsupportedEncodingException
274 {
275 this(new BufferedWriter(new OutputStreamWriter(new FileOutputStream(file), csn)),
276 false);
277 }
278
279 /** Checks to make sure that the stream has not been closed */
280 private void ensureOpen() throws IOException {
281 if (out == null)
282 throw new IOException("Stream closed");
283 }
284
285 /**
286 * Flushes the stream.
287 * @see #checkError()
288 */
289 public void flush() {
290 try {
291 synchronized (lock) {
292 ensureOpen();
293 out.flush();
294 }
295 }
296 catch (IOException x) {
297 trouble = true;
298 }
299 }
300
301 /**
302 * Closes the stream and releases any system resources associated
303 * with it. Closing a previously closed stream has no effect.
304 *
305 * @see #checkError()
306 */
307 public void close() {
308 try {
309 synchronized (lock) {
310 if (out == null)
311 return;
312 out.close();
313 out = null;
314 }
315 }
316 catch (IOException x) {
317 trouble = true;
318 }
319 }
320
321 /**
322 * Flushes the stream if it's not closed and checks its error state.
323 *
324 * @return <code>true</code> if the print stream has encountered an error,
325 * either on the underlying output stream or during a format
326 * conversion.
327 */
328 public boolean checkError() {
329 if (out != null) {
330 flush();
331 }
332 if (out instanceof java.io.PrintWriter) {
333 PrintWriter pw = (PrintWriter) out;
334 return pw.checkError();
335 } else if (psOut != null) {
336 return psOut.checkError();
337 }
338 return trouble;
339 }
340
341 /**
342 * Indicates that an error has occurred.
343 *
344 * <p> This method will cause subsequent invocations of {@link
345 * #checkError()} to return <tt>true</tt> until {@link
346 * #clearError()} is invoked.
347 */
348 protected void setError() {
349 trouble = true;
350 }
351
352 /**
353 * Clears the error state of this stream.
354 *
355 * <p> This method will cause subsequent invocations of {@link
356 * #checkError()} to return <tt>false</tt> until another write
357 * operation fails and invokes {@link #setError()}.
358 *
359 * @since 1.6
360 */
361 protected void clearError() {
362 trouble = false;
363 }
364
365 /*
366 * Exception-catching, synchronized output operations,
367 * which also implement the write() methods of Writer
368 */
369
370 /**
371 * Writes a single character.
372 * @param c int specifying a character to be written.
373 */
374 public void write(int c) {
375 try {
376 synchronized (lock) {
377 ensureOpen();
378 out.write(c);
379 }
380 }
381 catch (InterruptedIOException x) {
382 Thread.currentThread().interrupt();
383 }
384 catch (IOException x) {
385 trouble = true;
386 }
387 }
388
389 /**
390 * Writes A Portion of an array of characters.
391 * @param buf Array of characters
392 * @param off Offset from which to start writing characters
393 * @param len Number of characters to write
394 */
395 public void write(char buf[], int off, int len) {
396 try {
397 synchronized (lock) {
398 ensureOpen();
399 out.write(buf, off, len);
400 }
401 }
402 catch (InterruptedIOException x) {
403 Thread.currentThread().interrupt();
404 }
405 catch (IOException x) {
406 trouble = true;
407 }
408 }
409
410 /**
411 * Writes an array of characters. This method cannot be inherited from the
412 * Writer class because it must suppress I/O exceptions.
413 * @param buf Array of characters to be written
414 */
415 public void write(char buf[]) {
416 write(buf, 0, buf.length);
417 }
418
419 /**
420 * Writes a portion of a string.
421 * @param s A String
422 * @param off Offset from which to start writing characters
423 * @param len Number of characters to write
424 */
425 public void write(String s, int off, int len) {
426 try {
427 synchronized (lock) {
428 ensureOpen();
429 out.write(s, off, len);
430 }
431 }
432 catch (InterruptedIOException x) {
433 Thread.currentThread().interrupt();
434 }
435 catch (IOException x) {
436 trouble = true;
437 }
438 }
439
440 /**
441 * Writes a string. This method cannot be inherited from the Writer class
442 * because it must suppress I/O exceptions.
443 * @param s String to be written
444 */
445 public void write(String s) {
446 write(s, 0, s.length());
447 }
448
449 private void newLine() {
450 try {
451 synchronized (lock) {
452 ensureOpen();
453 out.write(lineSeparator);
454 if (autoFlush)
455 out.flush();
456 }
457 }
458 catch (InterruptedIOException x) {
459 Thread.currentThread().interrupt();
460 }
461 catch (IOException x) {
462 trouble = true;
463 }
464 }
465
466 /* Methods that do not terminate lines */
467
468 /**
469 * Prints a boolean value. The string produced by <code>{@link
470 * java.lang.String#valueOf(boolean)}</code> is translated into bytes
471 * according to the platform's default character encoding, and these bytes
472 * are written in exactly the manner of the <code>{@link
473 * #write(int)}</code> method.
474 *
475 * @param b The <code>boolean</code> to be printed
476 */
477 public void print(boolean b) {
478 write(b ? "true" : "false");
479 }
480
481 /**
482 * Prints a character. The character is translated into one or more bytes
483 * according to the platform's default character encoding, and these bytes
484 * are written in exactly the manner of the <code>{@link
485 * #write(int)}</code> method.
486 *
487 * @param c The <code>char</code> to be printed
488 */
489 public void print(char c) {
490 write(c);
491 }
492
493 /**
494 * Prints an integer. The string produced by <code>{@link
495 * java.lang.String#valueOf(int)}</code> is translated into bytes according
496 * to the platform's default character encoding, and these bytes are
497 * written in exactly the manner of the <code>{@link #write(int)}</code>
498 * method.
499 *
500 * @param i The <code>int</code> to be printed
501 * @see java.lang.Integer#toString(int)
502 */
503 public void print(int i) {
504 write(String.valueOf(i));
505 }
506
507 /**
508 * Prints a long integer. The string produced by <code>{@link
509 * java.lang.String#valueOf(long)}</code> is translated into bytes
510 * according to the platform's default character encoding, and these bytes
511 * are written in exactly the manner of the <code>{@link #write(int)}</code>
512 * method.
513 *
514 * @param l The <code>long</code> to be printed
515 * @see java.lang.Long#toString(long)
516 */
517 public void print(long l) {
518 write(String.valueOf(l));
519 }
520
521 /**
522 * Prints a floating-point number. The string produced by <code>{@link
523 * java.lang.String#valueOf(float)}</code> is translated into bytes
524 * according to the platform's default character encoding, and these bytes
525 * are written in exactly the manner of the <code>{@link #write(int)}</code>
526 * method.
527 *
528 * @param f The <code>float</code> to be printed
529 * @see java.lang.Float#toString(float)
530 */
531 public void print(float f) {
532 write(String.valueOf(f));
533 }
534
535 /**
536 * Prints a double-precision floating-point number. The string produced by
537 * <code>{@link java.lang.String#valueOf(double)}</code> is translated into
538 * bytes according to the platform's default character encoding, and these
539 * bytes are written in exactly the manner of the <code>{@link
540 * #write(int)}</code> method.
541 *
542 * @param d The <code>double</code> to be printed
543 * @see java.lang.Double#toString(double)
544 */
545 public void print(double d) {
546 write(String.valueOf(d));
547 }
548
549 /**
550 * Prints an array of characters. The characters are converted into bytes
551 * according to the platform's default character encoding, and these bytes
552 * are written in exactly the manner of the <code>{@link #write(int)}</code>
553 * method.
554 *
555 * @param s The array of chars to be printed
556 *
557 * @throws NullPointerException If <code>s</code> is <code>null</code>
558 */
559 public void print(char s[]) {
560 write(s);
561 }
562
563 /**
564 * Prints a string. If the argument is <code>null</code> then the string
565 * <code>"null"</code> is printed. Otherwise, the string's characters are
566 * converted into bytes according to the platform's default character
567 * encoding, and these bytes are written in exactly the manner of the
568 * <code>{@link #write(int)}</code> method.
569 *
570 * @param s The <code>String</code> to be printed
571 */
572 public void print(String s) {
573 if (s == null) {
574 s = "null";
575 }
576 write(s);
577 }
578
579 /**
580 * Prints an object. The string produced by the <code>{@link
581 * java.lang.String#valueOf(Object)}</code> method is translated into bytes
582 * according to the platform's default character encoding, and these bytes
583 * are written in exactly the manner of the <code>{@link #write(int)}</code>
584 * method.
585 *
586 * @param obj The <code>Object</code> to be printed
587 * @see java.lang.Object#toString()
588 */
589 public void print(Object obj) {
590 write(String.valueOf(obj));
591 }
592
593 /* Methods that do terminate lines */
594
595 /**
596 * Terminates the current line by writing the line separator string. The
597 * line separator string is defined by the system property
598 * <code>line.separator</code>, and is not necessarily a single newline
599 * character (<code>'\n'</code>).
600 */
601 public void println() {
602 newLine();
603 }
604
605 /**
606 * Prints a boolean value and then terminates the line. This method behaves
607 * as though it invokes <code>{@link #print(boolean)}</code> and then
608 * <code>{@link #println()}</code>.
609 *
610 * @param x the <code>boolean</code> value to be printed
611 */
612 public void println(boolean x) {
613 synchronized (lock) {
614 print(x);
615 println();
616 }
617 }
618
619 /**
620 * Prints a character and then terminates the line. This method behaves as
621 * though it invokes <code>{@link #print(char)}</code> and then <code>{@link
622 * #println()}</code>.
623 *
624 * @param x the <code>char</code> value to be printed
625 */
626 public void println(char x) {
627 synchronized (lock) {
628 print(x);
629 println();
630 }
631 }
632
633 /**
634 * Prints an integer and then terminates the line. This method behaves as
635 * though it invokes <code>{@link #print(int)}</code> and then <code>{@link
636 * #println()}</code>.
637 *
638 * @param x the <code>int</code> value to be printed
639 */
640 public void println(int x) {
641 synchronized (lock) {
642 print(x);
643 println();
644 }
645 }
646
647 /**
648 * Prints a long integer and then terminates the line. This method behaves
649 * as though it invokes <code>{@link #print(long)}</code> and then
650 * <code>{@link #println()}</code>.
651 *
652 * @param x the <code>long</code> value to be printed
653 */
654 public void println(long x) {
655 synchronized (lock) {
656 print(x);
657 println();
658 }
659 }
660
661 /**
662 * Prints a floating-point number and then terminates the line. This method
663 * behaves as though it invokes <code>{@link #print(float)}</code> and then
664 * <code>{@link #println()}</code>.
665 *
666 * @param x the <code>float</code> value to be printed
667 */
668 public void println(float x) {
669 synchronized (lock) {
670 print(x);
671 println();
672 }
673 }
674
675 /**
676 * Prints a double-precision floating-point number and then terminates the
677 * line. This method behaves as though it invokes <code>{@link
678 * #print(double)}</code> and then <code>{@link #println()}</code>.
679 *
680 * @param x the <code>double</code> value to be printed
681 */
682 public void println(double x) {
683 synchronized (lock) {
684 print(x);
685 println();
686 }
687 }
688
689 /**
690 * Prints an array of characters and then terminates the line. This method
691 * behaves as though it invokes <code>{@link #print(char[])}</code> and then
692 * <code>{@link #println()}</code>.
693 *
694 * @param x the array of <code>char</code> values to be printed
695 */
696 public void println(char x[]) {
697 synchronized (lock) {
698 print(x);
699 println();
700 }
701 }
702
703 /**
704 * Prints a String and then terminates the line. This method behaves as
705 * though it invokes <code>{@link #print(String)}</code> and then
706 * <code>{@link #println()}</code>.
707 *
708 * @param x the <code>String</code> value to be printed
709 */
710 public void println(String x) {
711 synchronized (lock) {
712 print(x);
713 println();
714 }
715 }
716
717 /**
718 * Prints an Object and then terminates the line. This method calls
719 * at first String.valueOf(x) to get the printed object's string value,
720 * then behaves as
721 * though it invokes <code>{@link #print(String)}</code> and then
722 * <code>{@link #println()}</code>.
723 *
724 * @param x The <code>Object</code> to be printed.
725 */
726 public void println(Object x) {
727 String s = String.valueOf(x);
728 synchronized (lock) {
729 print(s);
730 println();
731 }
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(format,
740 * args)</tt> behaves in exactly the same way as the invocation
741 *
742 * <pre>
743 * out.format(format, args) </pre>
744 *
745 * @param format
746 * A format string as described in <a
747 * href="../util/Formatter.html#syntax">Format string syntax</a>.
748 *
749 * @param args
750 * Arguments referenced by the format specifiers in the format
751 * string. If there are more arguments than format specifiers, the
752 * extra arguments are ignored. The number of arguments is
753 * variable and may be zero. The maximum number of arguments is
754 * limited by the maximum dimension of a Java array as defined by
755 * the <a href="http://java.sun.com/docs/books/vmspec/">Java
756 * Virtual Machine Specification</a>. The behaviour on a
757 * <tt>null</tt> argument depends on the <a
758 * href="../util/Formatter.html#syntax">conversion</a>.
759 *
760 * @throws IllegalFormatException
761 * If a format string contains an illegal syntax, a format
762 * specifier that is incompatible with the given arguments,
763 * insufficient arguments given the format string, or other
764 * illegal conditions. For specification of all possible
765 * formatting errors, see the <a
766 * href="../util/Formatter.html#detail">Details</a> section of the
767 * formatter class specification.
768 *
769 * @throws NullPointerException
770 * If the <tt>format</tt> is <tt>null</tt>
771 *
772 * @return This writer
773 *
774 * @since 1.5
775 */
776 public PrintWriter printf(String format, Object ... args) {
777 return format(format, args);
778 }
779
780 /**
781 * A convenience method to write a formatted string to this writer using
782 * the specified format string and arguments. If automatic flushing is
783 * enabled, calls to this method will flush the output buffer.
784 *
785 * <p> An invocation of this method of the form <tt>out.printf(l, format,
786 * args)</tt> behaves in exactly the same way as the invocation
787 *
788 * <pre>
789 * out.format(l, format, args) </pre>
790 *
791 * @param l
792 * The {@linkplain java.util.Locale locale} to apply during
793 * formatting. If <tt>l</tt> is <tt>null</tt> then no localization
794 * is applied.
795 *
796 * @param format
797 * A format string as described in <a
798 * href="../util/Formatter.html#syntax">Format string syntax</a>.
799 *
800 * @param args
801 * Arguments referenced by the format specifiers in the format
802 * string. If there are more arguments than format specifiers, the
803 * extra arguments are ignored. The number of arguments is
804 * variable and may be zero. The maximum number of arguments is
805 * limited by the maximum dimension of a Java array as defined by
806 * the <a href="http://java.sun.com/docs/books/vmspec/">Java
807 * Virtual Machine Specification</a>. The behaviour on a
808 * <tt>null</tt> argument depends on the <a
809 * href="../util/Formatter.html#syntax">conversion</a>.
810 *
811 * @throws IllegalFormatException
812 * If a format string contains an illegal syntax, a format
813 * specifier that is incompatible with the given arguments,
814 * insufficient arguments given the format string, or other
815 * illegal conditions. For specification of all possible
816 * formatting errors, see the <a
817 * href="../util/Formatter.html#detail">Details</a> section of the
818 * formatter class specification.
819 *
820 * @throws NullPointerException
821 * If the <tt>format</tt> is <tt>null</tt>
822 *
823 * @return This writer
824 *
825 * @since 1.5
826 */
827 public PrintWriter printf(Locale l, String format, Object ... args) {
828 return format(l, format, args);
829 }
830
831 /**
832 * Writes a formatted string to this writer using the specified format
833 * string and arguments. If automatic flushing is enabled, calls to this
834 * method will flush the output buffer.
835 *
836 * <p> The locale always used is the one returned by {@link
837 * java.util.Locale#getDefault() Locale.getDefault()}, regardless of any
838 * previous invocations of other formatting methods on this object.
839 *
840 * @param format
841 * A format string as described in <a
842 * href="../util/Formatter.html#syntax">Format string syntax</a>.
843 *
844 * @param args
845 * Arguments referenced by the format specifiers in the format
846 * string. If there are more arguments than format specifiers, the
847 * extra arguments are ignored. The number of arguments is
848 * variable and may be zero. The maximum number of arguments is
849 * limited by the maximum dimension of a Java array as defined by
850 * the <a href="http://java.sun.com/docs/books/vmspec/">Java
851 * Virtual Machine Specification</a>. The behaviour on a
852 * <tt>null</tt> argument depends on the <a
853 * href="../util/Formatter.html#syntax">conversion</a>.
854 *
855 * @throws IllegalFormatException
856 * If a format string contains an illegal syntax, a format
857 * specifier that is incompatible with the given arguments,
858 * insufficient arguments given the format string, or other
859 * illegal conditions. For specification of all possible
860 * formatting errors, see the <a
861 * href="../util/Formatter.html#detail">Details</a> section of the
862 * Formatter class specification.
863 *
864 * @throws NullPointerException
865 * If the <tt>format</tt> is <tt>null</tt>
866 *
867 * @return This writer
868 *
869 * @since 1.5
870 */
871 public PrintWriter format(String format, Object ... args) {
872 try {
873 synchronized (lock) {
874 ensureOpen();
875 if ((formatter == null)
876 || (formatter.locale() != Locale.getDefault()))
877 formatter = new Formatter(this);
878 formatter.format(Locale.getDefault(), format, args);
879 if (autoFlush)
880 out.flush();
881 }
882 } catch (InterruptedIOException x) {
883 Thread.currentThread().interrupt();
884 } catch (IOException x) {
885 trouble = true;
886 }
887 return this;
888 }
889
890 /**
891 * Writes a formatted string to this writer using the specified format
892 * string and arguments. If automatic flushing is enabled, calls to this
893 * method will flush the output buffer.
894 *
895 * @param l
896 * The {@linkplain java.util.Locale locale} to apply during
897 * formatting. If <tt>l</tt> is <tt>null</tt> then no localization
898 * is applied.
899 *
900 * @param format
901 * A format string as described in <a
902 * href="../util/Formatter.html#syntax">Format string syntax</a>.
903 *
904 * @param args
905 * Arguments referenced by the format specifiers in the format
906 * string. If there are more arguments than format specifiers, the
907 * extra arguments are ignored. The number of arguments is
908 * variable and may be zero. The maximum number of arguments is
909 * limited by the maximum dimension of a Java array as defined by
910 * the <a href="http://java.sun.com/docs/books/vmspec/">Java
911 * Virtual Machine Specification</a>. The behaviour on a
912 * <tt>null</tt> argument depends on the <a
913 * href="../util/Formatter.html#syntax">conversion</a>.
914 *
915 * @throws IllegalFormatException
916 * If a format string contains an illegal syntax, a format
917 * specifier that is incompatible with the given arguments,
918 * insufficient arguments given the format string, or other
919 * illegal conditions. For specification of all possible
920 * formatting errors, see the <a
921 * href="../util/Formatter.html#detail">Details</a> section of the
922 * formatter class specification.
923 *
924 * @throws NullPointerException
925 * If the <tt>format</tt> is <tt>null</tt>
926 *
927 * @return This writer
928 *
929 * @since 1.5
930 */
931 public PrintWriter format(Locale l, String format, Object ... args) {
932 try {
933 synchronized (lock) {
934 ensureOpen();
935 if ((formatter == null) || (formatter.locale() != l))
936 formatter = new Formatter(this, l);
937 formatter.format(l, format, args);
938 if (autoFlush)
939 out.flush();
940 }
941 } catch (InterruptedIOException x) {
942 Thread.currentThread().interrupt();
943 } catch (IOException x) {
944 trouble = true;
945 }
946 return this;
947 }
948
949 /**
950 * Appends the specified character sequence to this writer.
951 *
952 * <p> An invocation of this method of the form <tt>out.append(csq)</tt>
953 * behaves in exactly the same way as the invocation
954 *
955 * <pre>
956 * out.write(csq.toString()) </pre>
957 *
958 * <p> Depending on the specification of <tt>toString</tt> for the
959 * character sequence <tt>csq</tt>, the entire sequence may not be
960 * appended. For instance, invoking the <tt>toString</tt> method of a
961 * character buffer will return a subsequence whose content depends upon
962 * the buffer's position and limit.
963 *
964 * @param csq
965 * The character sequence to append. If <tt>csq</tt> is
966 * <tt>null</tt>, then the four characters <tt>"null"</tt> are
967 * appended to this writer.
968 *
969 * @return This writer
970 *
971 * @since 1.5
972 */
973 public PrintWriter append(CharSequence csq) {
974 if (csq == null)
975 write("null");
976 else
977 write(csq.toString());
978 return this;
979 }
980
981 /**
982 * Appends a subsequence of the specified character sequence to this writer.
983 *
984 * <p> An invocation of this method of the form <tt>out.append(csq, start,
985 * end)</tt> when <tt>csq</tt> is not <tt>null</tt>, behaves in
986 * exactly the same way as the invocation
987 *
988 * <pre>
989 * out.write(csq.subSequence(start, end).toString()) </pre>
990 *
991 * @param csq
992 * The character sequence from which a subsequence will be
993 * appended. If <tt>csq</tt> is <tt>null</tt>, then characters
994 * will be appended as if <tt>csq</tt> contained the four
995 * characters <tt>"null"</tt>.
996 *
997 * @param start
998 * The index of the first character in the subsequence
999 *
1000 * @param end
1001 * The index of the character following the last character in the
1002 * subsequence
1003 *
1004 * @return This writer
1005 *
1006 * @throws IndexOutOfBoundsException
1007 * If <tt>start</tt> or <tt>end</tt> are negative, <tt>start</tt>
1008 * is greater than <tt>end</tt>, or <tt>end</tt> is greater than
1009 * <tt>csq.length()</tt>
1010 *
1011 * @since 1.5
1012 */
1013 public PrintWriter append(CharSequence csq, int start, int end) {
1014 CharSequence cs = (csq == null ? "null" : csq);
1015 write(cs.subSequence(start, end).toString());
1016 return this;
1017 }
1018
1019 /**
1020 * Appends the specified character to this writer.
1021 *
1022 * <p> An invocation of this method of the form <tt>out.append(c)</tt>
1023 * behaves in exactly the same way as the invocation
1024 *
1025 * <pre>
1026 * out.write(c) </pre>
1027 *
1028 * @param c
1029 * The 16-bit character to append
1030 *
1031 * @return This writer
1032 *
1033 * @since 1.5
1034 */
1035 public PrintWriter append(char c) {
1036 write(c);
1037 return this;
1038 }
1039 }