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