1 /*
2 * Copyright (c) 1996, 2017, 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 import java.nio.charset.Charset;
31 import java.nio.charset.IllegalCharsetNameException;
32 import java.nio.charset.UnsupportedCharsetException;
33
34 /**
35 * A {@code PrintStream} adds functionality to another output stream,
36 * namely the ability to print representations of various data values
37 * conveniently. Two other features are provided as well. Unlike other output
38 * streams, a {@code PrintStream} never throws an
39 * {@code IOException}; instead, exceptional situations merely set an
40 * internal flag that can be tested via the {@code checkError} method.
41 * Optionally, a {@code PrintStream} can be created so as to flush
42 * automatically; this means that the {@code flush} method is
43 * automatically invoked after a byte array is written, one of the
44 * {@code println} methods is invoked, or a newline character or byte
45 * ({@code '\n'}) is written.
46 *
47 * <p> All characters printed by a {@code PrintStream} are converted into
48 * bytes using the given encoding or charset, or platform's default character
49 * encoding if not specified.
50 * The {@link PrintWriter} class should be used in situations that require
51 * writing characters rather than bytes.
52 *
53 * <p> This class always replaces malformed and unmappable character sequences with
54 * the charset's default replacement string.
55 * The {@linkplain java.nio.charset.CharsetEncoder} class should be used when more
56 * control over the encoding process is required.
57 *
58 * @author Frank Yellin
59 * @author Mark Reinhold
60 * @since 1.0
61 */
62
63 public class PrintStream extends FilterOutputStream
64 implements Appendable, Closeable
65 {
66
67 private final boolean autoFlush;
68 private boolean trouble = false;
69 private Formatter formatter;
70
71 /**
72 * Track both the text- and character-output streams, so that their buffers
73 * can be flushed without flushing the entire stream.
74 */
75 private BufferedWriter textOut;
76 private OutputStreamWriter charOut;
77
78 /**
79 * requireNonNull is explicitly declared here so as not to create an extra
80 * dependency on java.util.Objects.requireNonNull. PrintStream is loaded
81 * early during system initialization.
82 */
83 private static <T> T requireNonNull(T obj, String message) {
84 if (obj == null)
85 throw new NullPointerException(message);
86 return obj;
87 }
88
89 /**
90 * Returns a charset object for the given charset name.
91 * @throws NullPointerException is csn is null
92 * @throws UnsupportedEncodingException if the charset is not supported
93 */
94 private static Charset toCharset(String csn)
95 throws UnsupportedEncodingException
96 {
97 requireNonNull(csn, "charsetName");
98 try {
99 return Charset.forName(csn);
100 } catch (IllegalCharsetNameException|UnsupportedCharsetException unused) {
101 // UnsupportedEncodingException should be thrown
102 throw new UnsupportedEncodingException(csn);
103 }
104 }
105
106 /* Private constructors */
107 private PrintStream(boolean autoFlush, OutputStream out) {
108 super(out);
109 this.autoFlush = autoFlush;
110 this.charOut = new OutputStreamWriter(this);
111 this.textOut = new BufferedWriter(charOut);
112 }
113
114 /* Variant of the private constructor so that the given charset name
115 * can be verified before evaluating the OutputStream argument. Used
116 * by constructors creating a FileOutputStream that also take a
117 * charset name.
118 */
119 private PrintStream(boolean autoFlush, Charset charset, OutputStream out) {
120 this(out, autoFlush, charset);
121 }
122
123 /**
124 * Creates a new print stream. This stream will not flush automatically.
125 *
126 * @param out The output stream to which values and objects will be
127 * printed
128 *
129 * @see java.io.PrintWriter#PrintWriter(java.io.OutputStream)
130 */
131 public PrintStream(OutputStream out) {
132 this(out, false);
133 }
134
135 /**
136 * Creates a new print stream.
137 *
138 * @param out The output stream to which values and objects will be
139 * printed
140 * @param autoFlush A boolean; if true, the output buffer will be flushed
141 * whenever a byte array is written, one of the
142 * {@code println} methods is invoked, or a newline
143 * character or byte ({@code '\n'}) is written
144 *
145 * @see java.io.PrintWriter#PrintWriter(java.io.OutputStream, boolean)
146 */
147 public PrintStream(OutputStream out, boolean autoFlush) {
148 this(autoFlush, requireNonNull(out, "Null output stream"));
149 }
150
151 /**
152 * Creates a new print stream.
153 *
154 * @param out The output stream to which values and objects will be
155 * printed
156 * @param autoFlush A boolean; if true, the output buffer will be flushed
157 * whenever a byte array is written, one of the
158 * {@code println} methods is invoked, or a newline
159 * character or byte ({@code '\n'}) is written
160 * @param encoding The name of a supported
161 * <a href="../lang/package-summary.html#charenc">
162 * character encoding</a>
163 *
164 * @throws UnsupportedEncodingException
165 * If the named encoding is not supported
166 *
167 * @since 1.4
168 */
169 public PrintStream(OutputStream out, boolean autoFlush, String encoding)
170 throws UnsupportedEncodingException
171 {
172 this(requireNonNull(out, "Null output stream"), autoFlush, toCharset(encoding));
173 }
174
175 /**
176 * Creates a new print stream, with the specified OutputStream, automatic line
177 * flushing and charset. This convenience constructor creates the necessary
178 * intermediate {@link java.io.OutputStreamWriter OutputStreamWriter},
179 * which will encode characters using the provided charset.
180 *
181 * @param out The output stream to which values and objects will be
182 * printed
183 * @param autoFlush A boolean; if true, the output buffer will be flushed
184 * whenever a byte array is written, one of the
185 * {@code println} methods is invoked, or a newline
186 * character or byte ({@code '\n'}) is written
187 * @param charset A {@linkplain java.nio.charset.Charset charset}
188 *
189 * @since 10
190 */
191 public PrintStream(OutputStream out, boolean autoFlush, Charset charset) {
192 super(out);
193 this.autoFlush = autoFlush;
194 this.charOut = new OutputStreamWriter(this, charset);
195 this.textOut = new BufferedWriter(charOut);
196 }
197
198 /**
199 * Creates a new print stream, without automatic line flushing, with the
200 * specified file name. This convenience constructor creates
201 * the necessary intermediate {@link java.io.OutputStreamWriter
202 * OutputStreamWriter}, which will encode characters using the
203 * {@linkplain java.nio.charset.Charset#defaultCharset() default charset}
204 * for this instance of the Java virtual machine.
205 *
206 * @param fileName
207 * The name of the file to use as the destination of this print
208 * stream. If the file exists, then it will be truncated to
209 * zero size; otherwise, a new file will be created. The output
210 * will be written to the file and is buffered.
211 *
212 * @throws FileNotFoundException
213 * If the given file object does not denote an existing, writable
214 * regular file and a new regular file of that name cannot be
215 * created, or if some other error occurs while opening or
216 * creating the file
217 *
218 * @throws SecurityException
219 * If a security manager is present and {@link
220 * SecurityManager#checkWrite checkWrite(fileName)} denies write
221 * access to the file
222 *
223 * @since 1.5
224 */
225 public PrintStream(String fileName) throws FileNotFoundException {
226 this(false, new FileOutputStream(fileName));
227 }
228
229 /**
230 * Creates a new print stream, without automatic line flushing, with the
231 * specified file name and charset. This convenience constructor creates
232 * the necessary intermediate {@link java.io.OutputStreamWriter
233 * OutputStreamWriter}, which will encode characters using the provided
234 * charset.
235 *
236 * @param fileName
237 * The name of the file to use as the destination of this print
238 * stream. If the file exists, then it will be truncated to
239 * zero size; otherwise, a new file will be created. The output
240 * will be written to the file and is buffered.
241 *
242 * @param csn
243 * The name of a supported {@linkplain java.nio.charset.Charset
244 * charset}
245 *
246 * @throws FileNotFoundException
247 * If the given file object does not denote an existing, writable
248 * regular file and a new regular file of that name cannot be
249 * created, or if some other error occurs while opening or
250 * creating the file
251 *
252 * @throws SecurityException
253 * If a security manager is present and {@link
254 * SecurityManager#checkWrite checkWrite(fileName)} denies write
255 * access to the file
256 *
257 * @throws UnsupportedEncodingException
258 * If the named charset is not supported
259 *
260 * @since 1.5
261 */
262 public PrintStream(String fileName, String csn)
263 throws FileNotFoundException, UnsupportedEncodingException
264 {
265 // ensure charset is checked before the file is opened
266 this(false, toCharset(csn), new FileOutputStream(fileName));
267 }
268
269 /**
270 * Creates a new print stream, without automatic line flushing, with the
271 * specified file name and charset. This convenience constructor creates
272 * the necessary intermediate {@link java.io.OutputStreamWriter
273 * OutputStreamWriter}, which will encode characters using the provided
274 * charset.
275 *
276 * @param fileName
277 * The name of the file to use as the destination of this print
278 * stream. If the file exists, then it will be truncated to
279 * zero size; otherwise, a new file will be created. The output
280 * will be written to the file and is buffered.
281 *
282 * @param charset
283 * A {@linkplain java.nio.charset.Charset charset}
284 *
285 * @throws IOException
286 * if an I/O error occurs while opening or creating the file
287 *
288 * @throws SecurityException
289 * If a security manager is present and {@link
290 * SecurityManager#checkWrite checkWrite(fileName)} denies write
291 * access to the file
292 *
293 * @since 10
294 */
295 public PrintStream(String fileName, Charset charset) throws IOException {
296 this(false, requireNonNull(charset, "charset"), new FileOutputStream(fileName));
297 }
298
299 /**
300 * Creates a new print stream, without automatic line flushing, with the
301 * specified file. This convenience constructor creates the necessary
302 * intermediate {@link java.io.OutputStreamWriter OutputStreamWriter},
303 * which will encode characters using the {@linkplain
304 * java.nio.charset.Charset#defaultCharset() default charset} for this
305 * instance of the Java virtual machine.
306 *
307 * @param file
308 * The file to use as the destination of this print stream. If the
309 * file exists, then it will be truncated to zero size; otherwise,
310 * a new file will be created. The output will be written to the
311 * file and is buffered.
312 *
313 * @throws FileNotFoundException
314 * If the given file object does not denote an existing, writable
315 * regular file and a new regular file of that name cannot be
316 * created, or if some other error occurs while opening or
317 * creating the file
318 *
319 * @throws SecurityException
320 * If a security manager is present and {@link
321 * SecurityManager#checkWrite checkWrite(file.getPath())}
322 * denies write access to the file
323 *
324 * @since 1.5
325 */
326 public PrintStream(File file) throws FileNotFoundException {
327 this(false, new FileOutputStream(file));
328 }
329
330 /**
331 * Creates a new print stream, without automatic line flushing, with the
332 * specified file and charset. This convenience constructor creates
333 * the necessary intermediate {@link java.io.OutputStreamWriter
334 * OutputStreamWriter}, which will encode characters using the provided
335 * charset.
336 *
337 * @param file
338 * The file to use as the destination of this print stream. If the
339 * file exists, then it will be truncated to zero size; otherwise,
340 * a new file will be created. The output will be written to the
341 * file and is buffered.
342 *
343 * @param csn
344 * The name of a supported {@linkplain java.nio.charset.Charset
345 * charset}
346 *
347 * @throws FileNotFoundException
348 * If the given file object does not denote an existing, writable
349 * regular file and a new regular file of that name cannot be
350 * created, or if some other error occurs while opening or
351 * creating the file
352 *
353 * @throws SecurityException
354 * If a security manager is present and {@link
355 * SecurityManager#checkWrite checkWrite(file.getPath())}
356 * denies write access to the file
357 *
358 * @throws UnsupportedEncodingException
359 * If the named charset is not supported
360 *
361 * @since 1.5
362 */
363 public PrintStream(File file, String csn)
364 throws FileNotFoundException, UnsupportedEncodingException
365 {
366 // ensure charset is checked before the file is opened
367 this(false, toCharset(csn), new FileOutputStream(file));
368 }
369
370
371 /**
372 * Creates a new print stream, without automatic line flushing, with the
373 * specified file and charset. This convenience constructor creates
374 * the necessary intermediate {@link java.io.OutputStreamWriter
375 * OutputStreamWriter}, which will encode characters using the provided
376 * charset.
377 *
378 * @param file
379 * The file to use as the destination of this print stream. If the
380 * file exists, then it will be truncated to zero size; otherwise,
381 * a new file will be created. The output will be written to the
382 * file and is buffered.
383 *
384 * @param charset
385 * A {@linkplain java.nio.charset.Charset charset}
386 *
387 * @throws IOException
388 * if an I/O error occurs while opening or creating the file
389 *
390 * @throws SecurityException
391 * If a security manager is present and {@link
392 * SecurityManager#checkWrite checkWrite(file.getPath())}
393 * denies write access to the file
394 *
395 * @since 10
396 */
397 public PrintStream(File file, Charset charset) throws IOException {
398 this(false, requireNonNull(charset, "charset"), new FileOutputStream(file));
399 }
400
401 /** Check to make sure that the stream has not been closed */
402 private void ensureOpen() throws IOException {
403 if (out == null)
404 throw new IOException("Stream closed");
405 }
406
407 /**
408 * Flushes the stream. This is done by writing any buffered output bytes to
409 * the underlying output stream and then flushing that stream.
410 *
411 * @see java.io.OutputStream#flush()
412 */
413 public void flush() {
414 synchronized (this) {
415 try {
416 ensureOpen();
417 out.flush();
418 }
419 catch (IOException x) {
420 trouble = true;
421 }
422 }
423 }
424
425 private boolean closing = false; /* To avoid recursive closing */
426
427 /**
428 * Closes the stream. This is done by flushing the stream and then closing
429 * the underlying output stream.
430 *
431 * @see java.io.OutputStream#close()
432 */
433 public void close() {
434 synchronized (this) {
435 if (! closing) {
436 closing = true;
437 try {
438 textOut.close();
439 out.close();
440 }
441 catch (IOException x) {
442 trouble = true;
443 }
444 textOut = null;
445 charOut = null;
446 out = null;
447 }
448 }
449 }
450
451 /**
452 * Flushes the stream and checks its error state. The internal error state
453 * is set to {@code true} when the underlying output stream throws an
454 * {@code IOException} other than {@code InterruptedIOException},
455 * and when the {@code setError} method is invoked. If an operation
456 * on the underlying output stream throws an
457 * {@code InterruptedIOException}, then the {@code PrintStream}
458 * converts the exception back into an interrupt by doing:
459 * <pre>{@code
460 * Thread.currentThread().interrupt();
461 * }</pre>
462 * or the equivalent.
463 *
464 * @return {@code true} if and only if this stream has encountered an
465 * {@code IOException} other than
466 * {@code InterruptedIOException}, or the
467 * {@code setError} method has been invoked
468 */
469 public boolean checkError() {
470 if (out != null)
471 flush();
472 if (out instanceof java.io.PrintStream) {
473 PrintStream ps = (PrintStream) out;
474 return ps.checkError();
475 }
476 return trouble;
477 }
478
479 /**
480 * Sets the error state of the stream to {@code true}.
481 *
482 * <p> This method will cause subsequent invocations of {@link
483 * #checkError()} to return {@code true} until
484 * {@link #clearError()} is invoked.
485 *
486 * @since 1.1
487 */
488 protected void setError() {
489 trouble = true;
490 }
491
492 /**
493 * Clears the internal error state of this stream.
494 *
495 * <p> This method will cause subsequent invocations of {@link
496 * #checkError()} to return {@code false} until another write
497 * operation fails and invokes {@link #setError()}.
498 *
499 * @since 1.6
500 */
501 protected void clearError() {
502 trouble = false;
503 }
504
505 /*
506 * Exception-catching, synchronized output operations,
507 * which also implement the write() methods of OutputStream
508 */
509
510 /**
511 * Writes the specified byte to this stream. If the byte is a newline and
512 * automatic flushing is enabled then the {@code flush} method will be
513 * invoked.
514 *
515 * <p> Note that the byte is written as given; to write a character that
516 * will be translated according to the platform's default character
517 * encoding, use the {@code print(char)} or {@code println(char)}
518 * methods.
519 *
520 * @param b The byte to be written
521 * @see #print(char)
522 * @see #println(char)
523 */
524 public void write(int b) {
525 try {
526 synchronized (this) {
527 ensureOpen();
528 out.write(b);
529 if ((b == '\n') && autoFlush)
530 out.flush();
531 }
532 }
533 catch (InterruptedIOException x) {
534 Thread.currentThread().interrupt();
535 }
536 catch (IOException x) {
537 trouble = true;
538 }
539 }
540
541 /**
542 * Writes {@code len} bytes from the specified byte array starting at
543 * offset {@code off} to this stream. If automatic flushing is
544 * enabled then the {@code flush} method will be invoked.
545 *
546 * <p> Note that the bytes will be written as given; to write characters
547 * that will be translated according to the platform's default character
548 * encoding, use the {@code print(char)} or {@code println(char)}
549 * methods.
550 *
551 * @param buf A byte array
552 * @param off Offset from which to start taking bytes
553 * @param len Number of bytes to write
554 */
555 public void write(byte buf[], int off, int len) {
556 try {
557 synchronized (this) {
558 ensureOpen();
559 out.write(buf, off, len);
560 if (autoFlush)
561 out.flush();
562 }
563 }
564 catch (InterruptedIOException x) {
565 Thread.currentThread().interrupt();
566 }
567 catch (IOException x) {
568 trouble = true;
569 }
570 }
571
572 /*
573 * The following private methods on the text- and character-output streams
574 * always flush the stream buffers, so that writes to the underlying byte
575 * stream occur as promptly as with the original PrintStream.
576 */
577
578 private void write(char[] buf) {
579 try {
580 synchronized (this) {
581 ensureOpen();
582 textOut.write(buf);
583 textOut.flushBuffer();
584 charOut.flushBuffer();
585 if (autoFlush) {
586 for (int i = 0; i < buf.length; i++)
587 if (buf[i] == '\n') {
588 out.flush();
589 break;
590 }
591 }
592 }
593 } catch (InterruptedIOException x) {
594 Thread.currentThread().interrupt();
595 } catch (IOException x) {
596 trouble = true;
597 }
598 }
599
600 // Used to optimize away back-to-back flushing and synchronization when
601 // using println, but since subclasses could exist which depend on
602 // observing a call to print followed by newLine() we only use this if
603 // getClass() == PrintStream.class to avoid compatibility issues.
604 private void writeln(char[] buf) {
605 try {
606 synchronized (this) {
607 ensureOpen();
608 textOut.write(buf);
609 textOut.newLine();
610 textOut.flushBuffer();
611 charOut.flushBuffer();
612 if (autoFlush)
613 out.flush();
614 }
615 }
616 catch (InterruptedIOException x) {
617 Thread.currentThread().interrupt();
618 }
619 catch (IOException x) {
620 trouble = true;
621 }
622 }
623
624 private void write(String s) {
625 try {
626 synchronized (this) {
627 ensureOpen();
628 textOut.write(s);
629 textOut.flushBuffer();
630 charOut.flushBuffer();
631 if (autoFlush && (s.indexOf('\n') >= 0))
632 out.flush();
633 }
634 }
635 catch (InterruptedIOException x) {
636 Thread.currentThread().interrupt();
637 }
638 catch (IOException x) {
639 trouble = true;
640 }
641 }
642
643 // Used to optimize away back-to-back flushing and synchronization when
644 // using println, but since subclasses could exist which depend on
645 // observing a call to print followed by newLine we only use this if
646 // getClass() == PrintStream.class to avoid compatibility issues.
647 private void writeln(String s) {
648 try {
649 synchronized (this) {
650 ensureOpen();
651 textOut.write(s);
652 textOut.newLine();
653 textOut.flushBuffer();
654 charOut.flushBuffer();
655 if (autoFlush)
656 out.flush();
657 }
658 }
659 catch (InterruptedIOException x) {
660 Thread.currentThread().interrupt();
661 }
662 catch (IOException x) {
663 trouble = true;
664 }
665 }
666
667 private void newLine() {
668 try {
669 synchronized (this) {
670 ensureOpen();
671 textOut.newLine();
672 textOut.flushBuffer();
673 charOut.flushBuffer();
674 if (autoFlush)
675 out.flush();
676 }
677 }
678 catch (InterruptedIOException x) {
679 Thread.currentThread().interrupt();
680 }
681 catch (IOException x) {
682 trouble = true;
683 }
684 }
685
686 /* Methods that do not terminate lines */
687
688 /**
689 * Prints a boolean value. The string produced by {@link
690 * java.lang.String#valueOf(boolean)} is translated into bytes
691 * according to the platform's default character encoding, and these bytes
692 * are written in exactly the manner of the
693 * {@link #write(int)} method.
694 *
695 * @param b The {@code boolean} to be printed
696 */
697 public void print(boolean b) {
698 write(String.valueOf(b));
699 }
700
701 /**
702 * Prints a character. The character is translated into one or more bytes
703 * according to the platform's default character encoding, and these bytes
704 * are written in exactly the manner of the
705 * {@link #write(int)} method.
706 *
707 * @param c The {@code char} to be printed
708 */
709 public void print(char c) {
710 write(String.valueOf(c));
711 }
712
713 /**
714 * Prints an integer. The string produced by {@link
715 * java.lang.String#valueOf(int)} is translated into bytes
716 * according to the platform's default character encoding, and these bytes
717 * are written in exactly the manner of the
718 * {@link #write(int)} method.
719 *
720 * @param i The {@code int} to be printed
721 * @see java.lang.Integer#toString(int)
722 */
723 public void print(int i) {
724 write(String.valueOf(i));
725 }
726
727 /**
728 * Prints a long integer. The string produced by {@link
729 * java.lang.String#valueOf(long)} is translated into bytes
730 * according to the platform's default character encoding, and these bytes
731 * are written in exactly the manner of the
732 * {@link #write(int)} method.
733 *
734 * @param l The {@code long} to be printed
735 * @see java.lang.Long#toString(long)
736 */
737 public void print(long l) {
738 write(String.valueOf(l));
739 }
740
741 /**
742 * Prints a floating-point number. The string produced by {@link
743 * java.lang.String#valueOf(float)} is translated into bytes
744 * according to the platform's default character encoding, and these bytes
745 * are written in exactly the manner of the
746 * {@link #write(int)} method.
747 *
748 * @param f The {@code float} to be printed
749 * @see java.lang.Float#toString(float)
750 */
751 public void print(float f) {
752 write(String.valueOf(f));
753 }
754
755 /**
756 * Prints a double-precision floating-point number. The string produced by
757 * {@link java.lang.String#valueOf(double)} is translated into
758 * bytes according to the platform's default character encoding, and these
759 * bytes are written in exactly the manner of the {@link
760 * #write(int)} method.
761 *
762 * @param d The {@code double} to be printed
763 * @see java.lang.Double#toString(double)
764 */
765 public void print(double d) {
766 write(String.valueOf(d));
767 }
768
769 /**
770 * Prints an array of characters. The characters are converted into bytes
771 * according to the platform's default character encoding, and these bytes
772 * are written in exactly the manner of the
773 * {@link #write(int)} method.
774 *
775 * @param s The array of chars to be printed
776 *
777 * @throws NullPointerException If {@code s} is {@code null}
778 */
779 public void print(char s[]) {
780 write(s);
781 }
782
783 /**
784 * Prints a string. If the argument is {@code null} then the string
785 * {@code "null"} is printed. Otherwise, the string's characters are
786 * converted into bytes according to the platform's default character
787 * encoding, and these bytes are written in exactly the manner of the
788 * {@link #write(int)} method.
789 *
790 * @param s The {@code String} to be printed
791 */
792 public void print(String s) {
793 write(String.valueOf(s));
794 }
795
796 /**
797 * Prints an object. The string produced by the {@link
798 * java.lang.String#valueOf(Object)} method is translated into bytes
799 * according to the platform's default character encoding, and these bytes
800 * are written in exactly the manner of the
801 * {@link #write(int)} method.
802 *
803 * @param obj The {@code Object} to be printed
804 * @see java.lang.Object#toString()
805 */
806 public void print(Object obj) {
807 write(String.valueOf(obj));
808 }
809
810
811 /* Methods that do terminate lines */
812
813 /**
814 * Terminates the current line by writing the line separator string. The
815 * line separator string is defined by the system property
816 * {@code line.separator}, and is not necessarily a single newline
817 * character ({@code '\n'}).
818 */
819 public void println() {
820 newLine();
821 }
822
823 /**
824 * Prints a boolean and then terminate the line. This method behaves as
825 * though it invokes {@link #print(boolean)} and then
826 * {@link #println()}.
827 *
828 * @param x The {@code boolean} to be printed
829 */
830 public void println(boolean x) {
831 if (getClass() == PrintStream.class) {
832 writeln(String.valueOf(x));
833 } else {
834 synchronized (this) {
835 print(x);
836 newLine();
837 }
838 }
839 }
840
841 /**
842 * Prints a character and then terminate the line. This method behaves as
843 * though it invokes {@link #print(char)} and then
844 * {@link #println()}.
845 *
846 * @param x The {@code char} to be printed.
847 */
848 public void println(char x) {
849 if (getClass() == PrintStream.class) {
850 writeln(String.valueOf(x));
851 } else {
852 synchronized (this) {
853 print(x);
854 newLine();
855 }
856 }
857 }
858
859 /**
860 * Prints an integer and then terminate the line. This method behaves as
861 * though it invokes {@link #print(int)} and then
862 * {@link #println()}.
863 *
864 * @param x The {@code int} to be printed.
865 */
866 public void println(int x) {
867 if (getClass() == PrintStream.class) {
868 writeln(String.valueOf(x));
869 } else {
870 synchronized (this) {
871 print(x);
872 newLine();
873 }
874 }
875 }
876
877 /**
878 * Prints a long and then terminate the line. This method behaves as
879 * though it invokes {@link #print(long)} and then
880 * {@link #println()}.
881 *
882 * @param x a The {@code long} to be printed.
883 */
884 public void println(long x) {
885 if (getClass() == PrintStream.class) {
886 writeln(String.valueOf(x));
887 } else {
888 synchronized (this) {
889 print(x);
890 newLine();
891 }
892 }
893 }
894
895 /**
896 * Prints a float and then terminate the line. This method behaves as
897 * though it invokes {@link #print(float)} and then
898 * {@link #println()}.
899 *
900 * @param x The {@code float} to be printed.
901 */
902 public void println(float x) {
903 if (getClass() == PrintStream.class) {
904 writeln(String.valueOf(x));
905 } else {
906 synchronized (this) {
907 print(x);
908 newLine();
909 }
910 }
911 }
912
913 /**
914 * Prints a double and then terminate the line. This method behaves as
915 * though it invokes {@link #print(double)} and then
916 * {@link #println()}.
917 *
918 * @param x The {@code double} to be printed.
919 */
920 public void println(double x) {
921 if (getClass() == PrintStream.class) {
922 writeln(String.valueOf(x));
923 } else {
924 synchronized (this) {
925 print(x);
926 newLine();
927 }
928 }
929 }
930
931 /**
932 * Prints an array of characters and then terminate the line. This method
933 * behaves as though it invokes {@link #print(char[])} and
934 * then {@link #println()}.
935 *
936 * @param x an array of chars to print.
937 */
938 public void println(char[] x) {
939 if (getClass() == PrintStream.class) {
940 writeln(x);
941 } else {
942 synchronized (this) {
943 print(x);
944 newLine();
945 }
946 }
947 }
948
949 /**
950 * Prints a String and then terminate the line. This method behaves as
951 * though it invokes {@link #print(String)} and then
952 * {@link #println()}.
953 *
954 * @param x The {@code String} to be printed.
955 */
956 public void println(String x) {
957 if (getClass() == PrintStream.class) {
958 writeln(String.valueOf(x));
959 } else {
960 synchronized (this) {
961 print(x);
962 newLine();
963 }
964 }
965 }
966
967 /**
968 * Prints an Object and then terminate the line. This method calls
969 * at first String.valueOf(x) to get the printed object's string value,
970 * then behaves as
971 * though it invokes {@link #print(String)} and then
972 * {@link #println()}.
973 *
974 * @param x The {@code Object} to be printed.
975 */
976 public void println(Object x) {
977 String s = String.valueOf(x);
978 if (getClass() == PrintStream.class) {
979 // need to apply String.valueOf again since first invocation
980 // might return null
981 writeln(String.valueOf(s));
982 } else {
983 synchronized (this) {
984 print(s);
985 newLine();
986 }
987 }
988 }
989
990
991 /**
992 * A convenience method to write a formatted string to this output stream
993 * using the specified format string and arguments.
994 *
995 * <p> An invocation of this method of the form
996 * {@code out.printf(format, args)} behaves
997 * in exactly the same way as the invocation
998 *
999 * <pre>{@code
1000 * out.format(format, args)
1001 * }</pre>
1002 *
1003 * @param format
1004 * A format string as described in <a
1005 * href="../util/Formatter.html#syntax">Format string syntax</a>
1006 *
1007 * @param args
1008 * Arguments referenced by the format specifiers in the format
1009 * string. If there are more arguments than format specifiers, the
1010 * extra arguments are ignored. The number of arguments is
1011 * variable and may be zero. The maximum number of arguments is
1012 * limited by the maximum dimension of a Java array as defined by
1013 * <cite>The Java™ Virtual Machine Specification</cite>.
1014 * The behaviour on a
1015 * {@code null} argument depends on the <a
1016 * href="../util/Formatter.html#syntax">conversion</a>.
1017 *
1018 * @throws java.util.IllegalFormatException
1019 * If a format string contains an illegal syntax, a format
1020 * specifier that is incompatible with the given arguments,
1021 * insufficient arguments given the format string, or other
1022 * illegal conditions. For specification of all possible
1023 * formatting errors, see the <a
1024 * href="../util/Formatter.html#detail">Details</a> section of the
1025 * formatter class specification.
1026 *
1027 * @throws NullPointerException
1028 * If the {@code format} is {@code null}
1029 *
1030 * @return This output stream
1031 *
1032 * @since 1.5
1033 */
1034 public PrintStream printf(String format, Object ... args) {
1035 return format(format, args);
1036 }
1037
1038 /**
1039 * A convenience method to write a formatted string to this output stream
1040 * using the specified format string and arguments.
1041 *
1042 * <p> An invocation of this method of the form
1043 * {@code out.printf(l, format, args)} behaves
1044 * in exactly the same way as the invocation
1045 *
1046 * <pre>{@code
1047 * out.format(l, format, args)
1048 * }</pre>
1049 *
1050 * @param l
1051 * The {@linkplain java.util.Locale locale} to apply during
1052 * formatting. If {@code l} is {@code null} then no localization
1053 * is applied.
1054 *
1055 * @param format
1056 * A format string as described in <a
1057 * href="../util/Formatter.html#syntax">Format string syntax</a>
1058 *
1059 * @param args
1060 * Arguments referenced by the format specifiers in the format
1061 * string. If there are more arguments than format specifiers, the
1062 * extra arguments are ignored. The number of arguments is
1063 * variable and may be zero. The maximum number of arguments is
1064 * limited by the maximum dimension of a Java array as defined by
1065 * <cite>The Java™ Virtual Machine Specification</cite>.
1066 * The behaviour on a
1067 * {@code null} argument depends on the <a
1068 * href="../util/Formatter.html#syntax">conversion</a>.
1069 *
1070 * @throws java.util.IllegalFormatException
1071 * If a format string contains an illegal syntax, a format
1072 * specifier that is incompatible with the given arguments,
1073 * insufficient arguments given the format string, or other
1074 * illegal conditions. For specification of all possible
1075 * formatting errors, see the <a
1076 * href="../util/Formatter.html#detail">Details</a> section of the
1077 * formatter class specification.
1078 *
1079 * @throws NullPointerException
1080 * If the {@code format} is {@code null}
1081 *
1082 * @return This output stream
1083 *
1084 * @since 1.5
1085 */
1086 public PrintStream printf(Locale l, String format, Object ... args) {
1087 return format(l, format, args);
1088 }
1089
1090 /**
1091 * Writes a formatted string to this output stream using the specified
1092 * format string and arguments.
1093 *
1094 * <p> The locale always used is the one returned by {@link
1095 * java.util.Locale#getDefault(Locale.Category)} with
1096 * {@link java.util.Locale.Category#FORMAT FORMAT} category specified,
1097 * regardless of any previous invocations of other formatting methods on
1098 * this object.
1099 *
1100 * @param format
1101 * A format string as described in <a
1102 * href="../util/Formatter.html#syntax">Format string syntax</a>
1103 *
1104 * @param args
1105 * Arguments referenced by the format specifiers in the format
1106 * string. If there are more arguments than format specifiers, the
1107 * extra arguments are ignored. The number of arguments is
1108 * variable and may be zero. The maximum number of arguments is
1109 * limited by the maximum dimension of a Java array as defined by
1110 * <cite>The Java™ Virtual Machine Specification</cite>.
1111 * The behaviour on a
1112 * {@code null} argument depends on the <a
1113 * href="../util/Formatter.html#syntax">conversion</a>.
1114 *
1115 * @throws java.util.IllegalFormatException
1116 * If a format string contains an illegal syntax, a format
1117 * specifier that is incompatible with the given arguments,
1118 * insufficient arguments given the format string, or other
1119 * illegal conditions. For specification of all possible
1120 * formatting errors, see the <a
1121 * href="../util/Formatter.html#detail">Details</a> section of the
1122 * formatter class specification.
1123 *
1124 * @throws NullPointerException
1125 * If the {@code format} is {@code null}
1126 *
1127 * @return This output stream
1128 *
1129 * @since 1.5
1130 */
1131 public PrintStream format(String format, Object ... args) {
1132 try {
1133 synchronized (this) {
1134 ensureOpen();
1135 if ((formatter == null)
1136 || (formatter.locale() !=
1137 Locale.getDefault(Locale.Category.FORMAT)))
1138 formatter = new Formatter((Appendable) this);
1139 formatter.format(Locale.getDefault(Locale.Category.FORMAT),
1140 format, args);
1141 }
1142 } catch (InterruptedIOException x) {
1143 Thread.currentThread().interrupt();
1144 } catch (IOException x) {
1145 trouble = true;
1146 }
1147 return this;
1148 }
1149
1150 /**
1151 * Writes a formatted string to this output stream using the specified
1152 * format string and arguments.
1153 *
1154 * @param l
1155 * The {@linkplain java.util.Locale locale} to apply during
1156 * formatting. If {@code l} is {@code null} then no localization
1157 * is applied.
1158 *
1159 * @param format
1160 * A format string as described in <a
1161 * href="../util/Formatter.html#syntax">Format string syntax</a>
1162 *
1163 * @param args
1164 * Arguments referenced by the format specifiers in the format
1165 * string. If there are more arguments than format specifiers, the
1166 * extra arguments are ignored. The number of arguments is
1167 * variable and may be zero. The maximum number of arguments is
1168 * limited by the maximum dimension of a Java array as defined by
1169 * <cite>The Java™ Virtual Machine Specification</cite>.
1170 * The behaviour on a
1171 * {@code null} argument depends on the <a
1172 * href="../util/Formatter.html#syntax">conversion</a>.
1173 *
1174 * @throws java.util.IllegalFormatException
1175 * If a format string contains an illegal syntax, a format
1176 * specifier that is incompatible with the given arguments,
1177 * insufficient arguments given the format string, or other
1178 * illegal conditions. For specification of all possible
1179 * formatting errors, see the <a
1180 * href="../util/Formatter.html#detail">Details</a> section of the
1181 * formatter class specification.
1182 *
1183 * @throws NullPointerException
1184 * If the {@code format} is {@code null}
1185 *
1186 * @return This output stream
1187 *
1188 * @since 1.5
1189 */
1190 public PrintStream format(Locale l, String format, Object ... args) {
1191 try {
1192 synchronized (this) {
1193 ensureOpen();
1194 if ((formatter == null)
1195 || (formatter.locale() != l))
1196 formatter = new Formatter(this, l);
1197 formatter.format(l, format, args);
1198 }
1199 } catch (InterruptedIOException x) {
1200 Thread.currentThread().interrupt();
1201 } catch (IOException x) {
1202 trouble = true;
1203 }
1204 return this;
1205 }
1206
1207 /**
1208 * Appends the specified character sequence to this output stream.
1209 *
1210 * <p> An invocation of this method of the form {@code out.append(csq)}
1211 * behaves in exactly the same way as the invocation
1212 *
1213 * <pre>{@code
1214 * out.print(csq.toString())
1215 * }</pre>
1216 *
1217 * <p> Depending on the specification of {@code toString} for the
1218 * character sequence {@code csq}, the entire sequence may not be
1219 * appended. For instance, invoking then {@code toString} method of a
1220 * character buffer will return a subsequence whose content depends upon
1221 * the buffer's position and limit.
1222 *
1223 * @param csq
1224 * The character sequence to append. If {@code csq} is
1225 * {@code null}, then the four characters {@code "null"} are
1226 * appended to this output stream.
1227 *
1228 * @return This output stream
1229 *
1230 * @since 1.5
1231 */
1232 public PrintStream append(CharSequence csq) {
1233 print(String.valueOf(csq));
1234 return this;
1235 }
1236
1237 /**
1238 * Appends a subsequence of the specified character sequence to this output
1239 * stream.
1240 *
1241 * <p> An invocation of this method of the form
1242 * {@code out.append(csq, start, end)} when
1243 * {@code csq} is not {@code null}, behaves in
1244 * exactly the same way as the invocation
1245 *
1246 * <pre>{@code
1247 * out.print(csq.subSequence(start, end).toString())
1248 * }</pre>
1249 *
1250 * @param csq
1251 * The character sequence from which a subsequence will be
1252 * appended. If {@code csq} is {@code null}, then characters
1253 * will be appended as if {@code csq} contained the four
1254 * characters {@code "null"}.
1255 *
1256 * @param start
1257 * The index of the first character in the subsequence
1258 *
1259 * @param end
1260 * The index of the character following the last character in the
1261 * subsequence
1262 *
1263 * @return This output stream
1264 *
1265 * @throws IndexOutOfBoundsException
1266 * If {@code start} or {@code end} are negative, {@code start}
1267 * is greater than {@code end}, or {@code end} is greater than
1268 * {@code csq.length()}
1269 *
1270 * @since 1.5
1271 */
1272 public PrintStream append(CharSequence csq, int start, int end) {
1273 if (csq == null) csq = "null";
1274 return append(csq.subSequence(start, end));
1275 }
1276
1277 /**
1278 * Appends the specified character to this output stream.
1279 *
1280 * <p> An invocation of this method of the form {@code out.append(c)}
1281 * behaves in exactly the same way as the invocation
1282 *
1283 * <pre>{@code
1284 * out.print(c)
1285 * }</pre>
1286 *
1287 * @param c
1288 * The 16-bit character to append
1289 *
1290 * @return This output stream
1291 *
1292 * @since 1.5
1293 */
1294 public PrintStream append(char c) {
1295 print(c);
1296 return this;
1297 }
1298
1299 }