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