1 /*
   2  * Copyright (c) 1996, 2019, 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      * Writes all bytes from the specified byte array to this stream.
 574      * If automatic flushing is enabled then the {@code flush} method
 575      * will be invoked.
 576      *
 577      * <p> Note that the bytes will be written as given; to write characters
 578      * that will be translated according to the platform's default character
 579      * encoding, use the {@code print(char[])} or {@code println(char[])}
 580      * methods.
 581      *
 582      * @apiNote
 583      * This method is equivalent to {@link #write(byte[],int,int)
 584      * write(b, 0, b.length)}.
 585      *
 586      * @param  buf   A byte array
 587      *
 588      * @since 14
 589      */
 590     public void writeBytes(byte buf[]) {
 591         this.write(buf, 0, buf.length);
 592     }
 593 
 594     /*
 595      * The following private methods on the text- and character-output streams
 596      * always flush the stream buffers, so that writes to the underlying byte
 597      * stream occur as promptly as with the original PrintStream.
 598      */
 599 
 600     private void write(char[] buf) {
 601         try {
 602             synchronized (this) {
 603                 ensureOpen();
 604                 textOut.write(buf);
 605                 textOut.flushBuffer();
 606                 charOut.flushBuffer();
 607                 if (autoFlush) {
 608                     for (int i = 0; i < buf.length; i++)
 609                         if (buf[i] == '\n') {
 610                             out.flush();
 611                             break;
 612                         }
 613                 }
 614             }
 615         } catch (InterruptedIOException x) {
 616             Thread.currentThread().interrupt();
 617         } catch (IOException x) {
 618             trouble = true;
 619         }
 620     }
 621 
 622     // Used to optimize away back-to-back flushing and synchronization when
 623     // using println, but since subclasses could exist which depend on
 624     // observing a call to print followed by newLine() we only use this if
 625     // getClass() == PrintStream.class to avoid compatibility issues.
 626     private void writeln(char[] buf) {
 627         try {
 628             synchronized (this) {
 629                 ensureOpen();
 630                 textOut.write(buf);
 631                 textOut.newLine();
 632                 textOut.flushBuffer();
 633                 charOut.flushBuffer();
 634                 if (autoFlush)
 635                     out.flush();
 636             }
 637         }
 638         catch (InterruptedIOException x) {
 639             Thread.currentThread().interrupt();
 640         }
 641         catch (IOException x) {
 642             trouble = true;
 643         }
 644     }
 645 
 646     private void write(String s) {
 647         try {
 648             synchronized (this) {
 649                 ensureOpen();
 650                 textOut.write(s);
 651                 textOut.flushBuffer();
 652                 charOut.flushBuffer();
 653                 if (autoFlush && (s.indexOf('\n') >= 0))
 654                     out.flush();
 655             }
 656         }
 657         catch (InterruptedIOException x) {
 658             Thread.currentThread().interrupt();
 659         }
 660         catch (IOException x) {
 661             trouble = true;
 662         }
 663     }
 664 
 665     // Used to optimize away back-to-back flushing and synchronization when
 666     // using println, but since subclasses could exist which depend on
 667     // observing a call to print followed by newLine we only use this if
 668     // getClass() == PrintStream.class to avoid compatibility issues.
 669     private void writeln(String s) {
 670         try {
 671             synchronized (this) {
 672                 ensureOpen();
 673                 textOut.write(s);
 674                 textOut.newLine();
 675                 textOut.flushBuffer();
 676                 charOut.flushBuffer();
 677                 if (autoFlush)
 678                     out.flush();
 679             }
 680         }
 681         catch (InterruptedIOException x) {
 682             Thread.currentThread().interrupt();
 683         }
 684         catch (IOException x) {
 685             trouble = true;
 686         }
 687     }
 688 
 689     private void newLine() {
 690         try {
 691             synchronized (this) {
 692                 ensureOpen();
 693                 textOut.newLine();
 694                 textOut.flushBuffer();
 695                 charOut.flushBuffer();
 696                 if (autoFlush)
 697                     out.flush();
 698             }
 699         }
 700         catch (InterruptedIOException x) {
 701             Thread.currentThread().interrupt();
 702         }
 703         catch (IOException x) {
 704             trouble = true;
 705         }
 706     }
 707 
 708     /* Methods that do not terminate lines */
 709 
 710     /**
 711      * Prints a boolean value.  The string produced by {@link
 712      * java.lang.String#valueOf(boolean)} is translated into bytes
 713      * according to the platform's default character encoding, and these bytes
 714      * are written in exactly the manner of the
 715      * {@link #write(int)} method.
 716      *
 717      * @param      b   The {@code boolean} to be printed
 718      */
 719     public void print(boolean b) {
 720         write(String.valueOf(b));
 721     }
 722 
 723     /**
 724      * Prints a character.  The character is translated into one or more bytes
 725      * according to the platform's default character encoding, and these bytes
 726      * are written in exactly the manner of the
 727      * {@link #write(int)} method.
 728      *
 729      * @param      c   The {@code char} to be printed
 730      */
 731     public void print(char c) {
 732         write(String.valueOf(c));
 733     }
 734 
 735     /**
 736      * Prints an integer.  The string produced by {@link
 737      * java.lang.String#valueOf(int)} is translated into bytes
 738      * according to the platform's default character encoding, and these bytes
 739      * are written in exactly the manner of the
 740      * {@link #write(int)} method.
 741      *
 742      * @param      i   The {@code int} to be printed
 743      * @see        java.lang.Integer#toString(int)
 744      */
 745     public void print(int i) {
 746         write(String.valueOf(i));
 747     }
 748 
 749     /**
 750      * Prints a long integer.  The string produced by {@link
 751      * java.lang.String#valueOf(long)} is translated into bytes
 752      * according to the platform's default character encoding, and these bytes
 753      * are written in exactly the manner of the
 754      * {@link #write(int)} method.
 755      *
 756      * @param      l   The {@code long} to be printed
 757      * @see        java.lang.Long#toString(long)
 758      */
 759     public void print(long l) {
 760         write(String.valueOf(l));
 761     }
 762 
 763     /**
 764      * Prints a floating-point number.  The string produced by {@link
 765      * java.lang.String#valueOf(float)} is translated into bytes
 766      * according to the platform's default character encoding, and these bytes
 767      * are written in exactly the manner of the
 768      * {@link #write(int)} method.
 769      *
 770      * @param      f   The {@code float} to be printed
 771      * @see        java.lang.Float#toString(float)
 772      */
 773     public void print(float f) {
 774         write(String.valueOf(f));
 775     }
 776 
 777     /**
 778      * Prints a double-precision floating-point number.  The string produced by
 779      * {@link java.lang.String#valueOf(double)} is translated into
 780      * bytes according to the platform's default character encoding, and these
 781      * bytes are written in exactly the manner of the {@link
 782      * #write(int)} method.
 783      *
 784      * @param      d   The {@code double} to be printed
 785      * @see        java.lang.Double#toString(double)
 786      */
 787     public void print(double d) {
 788         write(String.valueOf(d));
 789     }
 790 
 791     /**
 792      * Prints an array of characters.  The characters are converted into bytes
 793      * according to the platform's default character encoding, and these bytes
 794      * are written in exactly the manner of the
 795      * {@link #write(int)} method.
 796      *
 797      * @param      s   The array of chars to be printed
 798      *
 799      * @throws  NullPointerException  If {@code s} is {@code null}
 800      */
 801     public void print(char s[]) {
 802         write(s);
 803     }
 804 
 805     /**
 806      * Prints a string.  If the argument is {@code null} then the string
 807      * {@code "null"} is printed.  Otherwise, the string's characters are
 808      * converted into bytes according to the platform's default character
 809      * encoding, and these bytes are written in exactly the manner of the
 810      * {@link #write(int)} method.
 811      *
 812      * @param      s   The {@code String} to be printed
 813      */
 814     public void print(String s) {
 815         write(String.valueOf(s));
 816     }
 817 
 818     /**
 819      * Prints an object.  The string produced by the {@link
 820      * java.lang.String#valueOf(Object)} method is translated into bytes
 821      * according to the platform's default character encoding, and these bytes
 822      * are written in exactly the manner of the
 823      * {@link #write(int)} method.
 824      *
 825      * @param      obj   The {@code Object} to be printed
 826      * @see        java.lang.Object#toString()
 827      */
 828     public void print(Object obj) {
 829         write(String.valueOf(obj));
 830     }
 831 
 832 
 833     /* Methods that do terminate lines */
 834 
 835     /**
 836      * Terminates the current line by writing the line separator string.  The
 837      * line separator string is defined by the system property
 838      * {@code line.separator}, and is not necessarily a single newline
 839      * character ({@code '\n'}).
 840      */
 841     public void println() {
 842         newLine();
 843     }
 844 
 845     /**
 846      * Prints a boolean and then terminate the line.  This method behaves as
 847      * though it invokes {@link #print(boolean)} and then
 848      * {@link #println()}.
 849      *
 850      * @param x  The {@code boolean} to be printed
 851      */
 852     public void println(boolean x) {
 853         if (getClass() == PrintStream.class) {
 854             writeln(String.valueOf(x));
 855         } else {
 856             synchronized (this) {
 857                 print(x);
 858                 newLine();
 859             }
 860         }
 861     }
 862 
 863     /**
 864      * Prints a character and then terminate the line.  This method behaves as
 865      * though it invokes {@link #print(char)} and then
 866      * {@link #println()}.
 867      *
 868      * @param x  The {@code char} to be printed.
 869      */
 870     public void println(char x) {
 871         if (getClass() == PrintStream.class) {
 872             writeln(String.valueOf(x));
 873         } else {
 874             synchronized (this) {
 875                 print(x);
 876                 newLine();
 877             }
 878         }
 879     }
 880 
 881     /**
 882      * Prints an integer and then terminate the line.  This method behaves as
 883      * though it invokes {@link #print(int)} and then
 884      * {@link #println()}.
 885      *
 886      * @param x  The {@code int} to be printed.
 887      */
 888     public void println(int x) {
 889         if (getClass() == PrintStream.class) {
 890             writeln(String.valueOf(x));
 891         } else {
 892             synchronized (this) {
 893                 print(x);
 894                 newLine();
 895             }
 896         }
 897     }
 898 
 899     /**
 900      * Prints a long and then terminate the line.  This method behaves as
 901      * though it invokes {@link #print(long)} and then
 902      * {@link #println()}.
 903      *
 904      * @param x  a The {@code long} to be printed.
 905      */
 906     public void println(long x) {
 907         if (getClass() == PrintStream.class) {
 908             writeln(String.valueOf(x));
 909         } else {
 910             synchronized (this) {
 911                 print(x);
 912                 newLine();
 913             }
 914         }
 915     }
 916 
 917     /**
 918      * Prints a float and then terminate the line.  This method behaves as
 919      * though it invokes {@link #print(float)} and then
 920      * {@link #println()}.
 921      *
 922      * @param x  The {@code float} to be printed.
 923      */
 924     public void println(float x) {
 925         if (getClass() == PrintStream.class) {
 926             writeln(String.valueOf(x));
 927         } else {
 928             synchronized (this) {
 929                 print(x);
 930                 newLine();
 931             }
 932         }
 933     }
 934 
 935     /**
 936      * Prints a double and then terminate the line.  This method behaves as
 937      * though it invokes {@link #print(double)} and then
 938      * {@link #println()}.
 939      *
 940      * @param x  The {@code double} to be printed.
 941      */
 942     public void println(double x) {
 943         if (getClass() == PrintStream.class) {
 944             writeln(String.valueOf(x));
 945         } else {
 946             synchronized (this) {
 947                 print(x);
 948                 newLine();
 949             }
 950         }
 951     }
 952 
 953     /**
 954      * Prints an array of characters and then terminate the line.  This method
 955      * behaves as though it invokes {@link #print(char[])} and
 956      * then {@link #println()}.
 957      *
 958      * @param x  an array of chars to print.
 959      */
 960     public void println(char[] x) {
 961         if (getClass() == PrintStream.class) {
 962             writeln(x);
 963         } else {
 964             synchronized (this) {
 965                 print(x);
 966                 newLine();
 967             }
 968         }
 969     }
 970 
 971     /**
 972      * Prints a String and then terminate the line.  This method behaves as
 973      * though it invokes {@link #print(String)} and then
 974      * {@link #println()}.
 975      *
 976      * @param x  The {@code String} to be printed.
 977      */
 978     public void println(String x) {
 979         if (getClass() == PrintStream.class) {
 980             writeln(String.valueOf(x));
 981         } else {
 982             synchronized (this) {
 983                 print(x);
 984                 newLine();
 985             }
 986         }
 987     }
 988 
 989     /**
 990      * Prints an Object and then terminate the line.  This method calls
 991      * at first String.valueOf(x) to get the printed object's string value,
 992      * then behaves as
 993      * though it invokes {@link #print(String)} and then
 994      * {@link #println()}.
 995      *
 996      * @param x  The {@code Object} to be printed.
 997      */
 998     public void println(Object x) {
 999         String s = String.valueOf(x);
1000         if (getClass() == PrintStream.class) {
1001             // need to apply String.valueOf again since first invocation
1002             // might return null
1003             writeln(String.valueOf(s));
1004         } else {
1005             synchronized (this) {
1006                 print(s);
1007                 newLine();
1008             }
1009         }
1010     }
1011 
1012 
1013     /**
1014      * A convenience method to write a formatted string to this output stream
1015      * using the specified format string and arguments.
1016      *
1017      * <p> An invocation of this method of the form
1018      * {@code out.printf(format, args)} behaves
1019      * in exactly the same way as the invocation
1020      *
1021      * <pre>{@code
1022      *     out.format(format, args)
1023      * }</pre>
1024      *
1025      * @param  format
1026      *         A format string as described in <a
1027      *         href="../util/Formatter.html#syntax">Format string syntax</a>
1028      *
1029      * @param  args
1030      *         Arguments referenced by the format specifiers in the format
1031      *         string.  If there are more arguments than format specifiers, the
1032      *         extra arguments are ignored.  The number of arguments is
1033      *         variable and may be zero.  The maximum number of arguments is
1034      *         limited by the maximum dimension of a Java array as defined by
1035      *         <cite>The Java&trade; Virtual Machine Specification</cite>.
1036      *         The behaviour on a
1037      *         {@code null} argument depends on the <a
1038      *         href="../util/Formatter.html#syntax">conversion</a>.
1039      *
1040      * @throws  java.util.IllegalFormatException
1041      *          If a format string contains an illegal syntax, a format
1042      *          specifier that is incompatible with the given arguments,
1043      *          insufficient arguments given the format string, or other
1044      *          illegal conditions.  For specification of all possible
1045      *          formatting errors, see the <a
1046      *          href="../util/Formatter.html#detail">Details</a> section of the
1047      *          formatter class specification.
1048      *
1049      * @throws  NullPointerException
1050      *          If the {@code format} is {@code null}
1051      *
1052      * @return  This output stream
1053      *
1054      * @since  1.5
1055      */
1056     public PrintStream printf(String format, Object ... args) {
1057         return format(format, args);
1058     }
1059 
1060     /**
1061      * A convenience method to write a formatted string to this output stream
1062      * using the specified format string and arguments.
1063      *
1064      * <p> An invocation of this method of the form
1065      * {@code out.printf(l, format, args)} behaves
1066      * in exactly the same way as the invocation
1067      *
1068      * <pre>{@code
1069      *     out.format(l, format, args)
1070      * }</pre>
1071      *
1072      * @param  l
1073      *         The {@linkplain java.util.Locale locale} to apply during
1074      *         formatting.  If {@code l} is {@code null} then no localization
1075      *         is applied.
1076      *
1077      * @param  format
1078      *         A format string as described in <a
1079      *         href="../util/Formatter.html#syntax">Format string syntax</a>
1080      *
1081      * @param  args
1082      *         Arguments referenced by the format specifiers in the format
1083      *         string.  If there are more arguments than format specifiers, the
1084      *         extra arguments are ignored.  The number of arguments is
1085      *         variable and may be zero.  The maximum number of arguments is
1086      *         limited by the maximum dimension of a Java array as defined by
1087      *         <cite>The Java&trade; Virtual Machine Specification</cite>.
1088      *         The behaviour on a
1089      *         {@code null} argument depends on the <a
1090      *         href="../util/Formatter.html#syntax">conversion</a>.
1091      *
1092      * @throws  java.util.IllegalFormatException
1093      *          If a format string contains an illegal syntax, a format
1094      *          specifier that is incompatible with the given arguments,
1095      *          insufficient arguments given the format string, or other
1096      *          illegal conditions.  For specification of all possible
1097      *          formatting errors, see the <a
1098      *          href="../util/Formatter.html#detail">Details</a> section of the
1099      *          formatter class specification.
1100      *
1101      * @throws  NullPointerException
1102      *          If the {@code format} is {@code null}
1103      *
1104      * @return  This output stream
1105      *
1106      * @since  1.5
1107      */
1108     public PrintStream printf(Locale l, String format, Object ... args) {
1109         return format(l, format, args);
1110     }
1111 
1112     /**
1113      * Writes a formatted string to this output stream using the specified
1114      * format string and arguments.
1115      *
1116      * <p> The locale always used is the one returned by {@link
1117      * java.util.Locale#getDefault(Locale.Category)} with
1118      * {@link java.util.Locale.Category#FORMAT FORMAT} category specified,
1119      * regardless of any previous invocations of other formatting methods on
1120      * this object.
1121      *
1122      * @param  format
1123      *         A format string as described in <a
1124      *         href="../util/Formatter.html#syntax">Format string syntax</a>
1125      *
1126      * @param  args
1127      *         Arguments referenced by the format specifiers in the format
1128      *         string.  If there are more arguments than format specifiers, the
1129      *         extra arguments are ignored.  The number of arguments is
1130      *         variable and may be zero.  The maximum number of arguments is
1131      *         limited by the maximum dimension of a Java array as defined by
1132      *         <cite>The Java&trade; Virtual Machine Specification</cite>.
1133      *         The behaviour on a
1134      *         {@code null} argument depends on the <a
1135      *         href="../util/Formatter.html#syntax">conversion</a>.
1136      *
1137      * @throws  java.util.IllegalFormatException
1138      *          If a format string contains an illegal syntax, a format
1139      *          specifier that is incompatible with the given arguments,
1140      *          insufficient arguments given the format string, or other
1141      *          illegal conditions.  For specification of all possible
1142      *          formatting errors, see the <a
1143      *          href="../util/Formatter.html#detail">Details</a> section of the
1144      *          formatter class specification.
1145      *
1146      * @throws  NullPointerException
1147      *          If the {@code format} is {@code null}
1148      *
1149      * @return  This output stream
1150      *
1151      * @since  1.5
1152      */
1153     public PrintStream format(String format, Object ... args) {
1154         try {
1155             synchronized (this) {
1156                 ensureOpen();
1157                 if ((formatter == null)
1158                     || (formatter.locale() !=
1159                         Locale.getDefault(Locale.Category.FORMAT)))
1160                     formatter = new Formatter((Appendable) this);
1161                 formatter.format(Locale.getDefault(Locale.Category.FORMAT),
1162                                  format, args);
1163             }
1164         } catch (InterruptedIOException x) {
1165             Thread.currentThread().interrupt();
1166         } catch (IOException x) {
1167             trouble = true;
1168         }
1169         return this;
1170     }
1171 
1172     /**
1173      * Writes a formatted string to this output stream using the specified
1174      * format string and arguments.
1175      *
1176      * @param  l
1177      *         The {@linkplain java.util.Locale locale} to apply during
1178      *         formatting.  If {@code l} is {@code null} then no localization
1179      *         is applied.
1180      *
1181      * @param  format
1182      *         A format string as described in <a
1183      *         href="../util/Formatter.html#syntax">Format string syntax</a>
1184      *
1185      * @param  args
1186      *         Arguments referenced by the format specifiers in the format
1187      *         string.  If there are more arguments than format specifiers, the
1188      *         extra arguments are ignored.  The number of arguments is
1189      *         variable and may be zero.  The maximum number of arguments is
1190      *         limited by the maximum dimension of a Java array as defined by
1191      *         <cite>The Java&trade; Virtual Machine Specification</cite>.
1192      *         The behaviour on a
1193      *         {@code null} argument depends on the <a
1194      *         href="../util/Formatter.html#syntax">conversion</a>.
1195      *
1196      * @throws  java.util.IllegalFormatException
1197      *          If a format string contains an illegal syntax, a format
1198      *          specifier that is incompatible with the given arguments,
1199      *          insufficient arguments given the format string, or other
1200      *          illegal conditions.  For specification of all possible
1201      *          formatting errors, see the <a
1202      *          href="../util/Formatter.html#detail">Details</a> section of the
1203      *          formatter class specification.
1204      *
1205      * @throws  NullPointerException
1206      *          If the {@code format} is {@code null}
1207      *
1208      * @return  This output stream
1209      *
1210      * @since  1.5
1211      */
1212     public PrintStream format(Locale l, String format, Object ... args) {
1213         try {
1214             synchronized (this) {
1215                 ensureOpen();
1216                 if ((formatter == null)
1217                     || (formatter.locale() != l))
1218                     formatter = new Formatter(this, l);
1219                 formatter.format(l, format, args);
1220             }
1221         } catch (InterruptedIOException x) {
1222             Thread.currentThread().interrupt();
1223         } catch (IOException x) {
1224             trouble = true;
1225         }
1226         return this;
1227     }
1228 
1229     /**
1230      * Appends the specified character sequence to this output stream.
1231      *
1232      * <p> An invocation of this method of the form {@code out.append(csq)}
1233      * behaves in exactly the same way as the invocation
1234      *
1235      * <pre>{@code
1236      *     out.print(csq.toString())
1237      * }</pre>
1238      *
1239      * <p> Depending on the specification of {@code toString} for the
1240      * character sequence {@code csq}, the entire sequence may not be
1241      * appended.  For instance, invoking then {@code toString} method of a
1242      * character buffer will return a subsequence whose content depends upon
1243      * the buffer's position and limit.
1244      *
1245      * @param  csq
1246      *         The character sequence to append.  If {@code csq} is
1247      *         {@code null}, then the four characters {@code "null"} are
1248      *         appended to this output stream.
1249      *
1250      * @return  This output stream
1251      *
1252      * @since  1.5
1253      */
1254     public PrintStream append(CharSequence csq) {
1255         print(String.valueOf(csq));
1256         return this;
1257     }
1258 
1259     /**
1260      * Appends a subsequence of the specified character sequence to this output
1261      * stream.
1262      *
1263      * <p> An invocation of this method of the form
1264      * {@code out.append(csq, start, end)} when
1265      * {@code csq} is not {@code null}, behaves in
1266      * exactly the same way as the invocation
1267      *
1268      * <pre>{@code
1269      *     out.print(csq.subSequence(start, end).toString())
1270      * }</pre>
1271      *
1272      * @param  csq
1273      *         The character sequence from which a subsequence will be
1274      *         appended.  If {@code csq} is {@code null}, then characters
1275      *         will be appended as if {@code csq} contained the four
1276      *         characters {@code "null"}.
1277      *
1278      * @param  start
1279      *         The index of the first character in the subsequence
1280      *
1281      * @param  end
1282      *         The index of the character following the last character in the
1283      *         subsequence
1284      *
1285      * @return  This output stream
1286      *
1287      * @throws  IndexOutOfBoundsException
1288      *          If {@code start} or {@code end} are negative, {@code start}
1289      *          is greater than {@code end}, or {@code end} is greater than
1290      *          {@code csq.length()}
1291      *
1292      * @since  1.5
1293      */
1294     public PrintStream append(CharSequence csq, int start, int end) {
1295         if (csq == null) csq = "null";
1296         return append(csq.subSequence(start, end));
1297     }
1298 
1299     /**
1300      * Appends the specified character to this output stream.
1301      *
1302      * <p> An invocation of this method of the form {@code out.append(c)}
1303      * behaves in exactly the same way as the invocation
1304      *
1305      * <pre>{@code
1306      *     out.print(c)
1307      * }</pre>
1308      *
1309      * @param  c
1310      *         The 16-bit character to append
1311      *
1312      * @return  This output stream
1313      *
1314      * @since  1.5
1315      */
1316     public PrintStream append(char c) {
1317         print(c);
1318         return this;
1319     }
1320 
1321 }