KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > io > PrintStream


1 /*
2  * @(#)PrintStream.java 1.32 04/07/16
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */

7
8 package java.io;
9
10 import java.util.Formatter JavaDoc;
11 import java.util.Locale JavaDoc;
12
13
14 /**
15  * A <code>PrintStream</code> adds functionality to another output stream,
16  * namely the ability to print representations of various data values
17  * conveniently. Two other features are provided as well. Unlike other output
18  * streams, a <code>PrintStream</code> never throws an
19  * <code>IOException</code>; instead, exceptional situations merely set an
20  * internal flag that can be tested via the <code>checkError</code> method.
21  * Optionally, a <code>PrintStream</code> can be created so as to flush
22  * automatically; this means that the <code>flush</code> method is
23  * automatically invoked after a byte array is written, one of the
24  * <code>println</code> methods is invoked, or a newline character or byte
25  * (<code>'\n'</code>) is written.
26  *
27  * <p> All characters printed by a <code>PrintStream</code> are converted into
28  * bytes using the platform's default character encoding. The <code>{@link
29  * PrintWriter}</code> class should be used in situations that require writing
30  * characters rather than bytes.
31  *
32  * @version 1.32, 04/07/16
33  * @author Frank Yellin
34  * @author Mark Reinhold
35  * @since JDK1.0
36  */

37
38 public class PrintStream extends FilterOutputStream JavaDoc
39     implements Appendable JavaDoc, Closeable JavaDoc
40 {
41
42     private boolean autoFlush = false;
43     private boolean trouble = false;
44     private Formatter JavaDoc formatter;
45
46     /**
47      * Track both the text- and character-output streams, so that their buffers
48      * can be flushed without flushing the entire stream.
49      */

50     private BufferedWriter JavaDoc textOut;
51     private OutputStreamWriter JavaDoc charOut;
52
53     /**
54      * Create a new print stream. This stream will not flush automatically.
55      *
56      * @param out The output stream to which values and objects will be
57      * printed
58      *
59      * @see java.io.PrintWriter#PrintWriter(java.io.OutputStream)
60      */

61     public PrintStream(OutputStream JavaDoc out) {
62     this(out, false);
63     }
64
65     /* Initialization is factored into a private constructor (note the swapped
66      * parameters so that this one isn't confused with the public one) and a
67      * separate init method so that the following two public constructors can
68      * share code. We use a separate init method so that the constructor that
69      * takes an encoding will throw an NPE for a null stream before it throws
70      * an UnsupportedEncodingException for an unsupported encoding.
71      */

72
73     private PrintStream(boolean autoFlush, OutputStream JavaDoc out)
74     {
75     super(out);
76     if (out == null)
77         throw new NullPointerException JavaDoc("Null output stream");
78     this.autoFlush = autoFlush;
79     }
80
81     private void init(OutputStreamWriter JavaDoc osw) {
82     this.charOut = osw;
83     this.textOut = new BufferedWriter JavaDoc(osw);
84     }
85
86     /**
87      * Create a new print stream.
88      *
89      * @param out The output stream to which values and objects will be
90      * printed
91      * @param autoFlush A boolean; if true, the output buffer will be flushed
92      * whenever a byte array is written, one of the
93      * <code>println</code> methods is invoked, or a newline
94      * character or byte (<code>'\n'</code>) is written
95      *
96      * @see java.io.PrintWriter#PrintWriter(java.io.OutputStream, boolean)
97      */

98     public PrintStream(OutputStream JavaDoc out, boolean autoFlush) {
99     this(autoFlush, out);
100     init(new OutputStreamWriter JavaDoc(this));
101     }
102
103     /**
104      * Create a new print stream.
105      *
106      * @param out The output stream to which values and objects will be
107      * printed
108      * @param autoFlush A boolean; if true, the output buffer will be flushed
109      * whenever a byte array is written, one of the
110      * <code>println</code> methods is invoked, or a newline
111      * character or byte (<code>'\n'</code>) is written
112      * @param encoding The name of a supported
113      * <a HREF="../lang/package-summary.html#charenc">
114      * character encoding</a>
115      *
116      * @exception UnsupportedEncodingException
117      * If the named encoding is not supported
118      */

119     public PrintStream(OutputStream JavaDoc out, boolean autoFlush, String JavaDoc encoding)
120         throws UnsupportedEncodingException JavaDoc
121     {
122     this(autoFlush, out);
123     init(new OutputStreamWriter JavaDoc(this, encoding));
124     }
125
126     /**
127      * Creates a new print stream, without automatic line flushing, with the
128      * specified file name. This convenience constructor creates
129      * the necessary intermediate {@link java.io.OutputStreamWriter
130      * OutputStreamWriter}, which will encode characters using the
131      * {@linkplain java.nio.charset.Charset#defaultCharset default charset}
132      * for this instance of the Java virtual machine.
133      *
134      * @param fileName
135      * The name of the file to use as the destination of this print
136      * stream. If the file exists, then it will be truncated to
137      * zero size; otherwise, a new file will be created. The output
138      * will be written to the file and is buffered.
139      *
140      * @throws FileNotFoundException
141      * If the given file object does not denote an existing, writable
142      * regular file and a new regular file of that name cannot be
143      * created, or if some other error occurs while opening or
144      * creating the file
145      *
146      * @throws SecurityException
147      * If a security manager is present and {@link
148      * SecurityManager#checkWrite checkWrite(fileName)} denies write
149      * access to the file
150      *
151      * @since 1.5
152      */

153     public PrintStream(String JavaDoc fileName) throws FileNotFoundException JavaDoc {
154     this(false, new FileOutputStream JavaDoc(fileName));
155     init(new OutputStreamWriter JavaDoc(this));
156     }
157
158     /**
159      * Creates a new print stream, without automatic line flushing, with the
160      * specified file name and charset. This convenience constructor creates
161      * the necessary intermediate {@link java.io.OutputStreamWriter
162      * OutputStreamWriter}, which will encode characters using the provided
163      * charset.
164      *
165      * @param fileName
166      * The name of the file to use as the destination of this print
167      * stream. If the file exists, then it will be truncated to
168      * zero size; otherwise, a new file will be created. The output
169      * will be written to the file and is buffered.
170      *
171      * @param csn
172      * The name of a supported {@linkplain java.nio.charset.Charset
173      * charset}
174      *
175      * @throws FileNotFoundException
176      * If the given file object does not denote an existing, writable
177      * regular file and a new regular file of that name cannot be
178      * created, or if some other error occurs while opening or
179      * creating the file
180      *
181      * @throws SecurityException
182      * If a security manager is present and {@link
183      * SecurityManager#checkWrite checkWrite(fileName)} denies write
184      * access to the file
185      *
186      * @throws UnsupportedEncodingException
187      * If the named charset is not supported
188      *
189      * @since 1.5
190      */

191     public PrintStream(String JavaDoc fileName, String JavaDoc csn)
192     throws FileNotFoundException JavaDoc, UnsupportedEncodingException JavaDoc
193     {
194     this(false, new FileOutputStream JavaDoc(fileName));
195     init(new OutputStreamWriter JavaDoc(this, csn));
196     }
197
198     /**
199      * Creates a new print stream, without automatic line flushing, with the
200      * specified file. This convenience constructor creates the necessary
201      * intermediate {@link java.io.OutputStreamWriter OutputStreamWriter},
202      * which will encode characters using the {@linkplain
203      * java.nio.charset.Charset#defaultCharset default charset} for this
204      * instance of the Java virtual machine.
205      *
206      * @param file
207      * The file to use as the destination of this print stream. If the
208      * file exists, then it will be truncated to zero size; otherwise,
209      * a new file will be created. The output will be written to the
210      * 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(file.getPath())}
221      * denies write access to the file
222      *
223      * @since 1.5
224      */

225     public PrintStream(File JavaDoc file) throws FileNotFoundException JavaDoc {
226     this(false, new FileOutputStream JavaDoc(file));
227     init(new OutputStreamWriter JavaDoc(this));
228     }
229
230     /**
231      * Creates a new print stream, without automatic line flushing, with the
232      * specified file and charset. This convenience constructor creates
233      * the necessary intermediate {@link java.io.OutputStreamWriter
234      * OutputStreamWriter}, which will encode characters using the provided
235      * charset.
236      *
237      * @param file
238      * The file to use as the destination of this print stream. If the
239      * file exists, then it will be truncated to zero size; otherwise,
240      * a new file will be created. The output will be written to the
241      * file and is buffered.
242      *
243      * @param csn
244      * The name of a supported {@linkplain java.nio.charset.Charset
245      * charset}
246      *
247      * @throws FileNotFoundException
248      * If the given file object does not denote an existing, writable
249      * regular file and a new regular file of that name cannot be
250      * created, or if some other error occurs while opening or
251      * creating the file
252      *
253      * @throws SecurityException
254      * If a security manager is presentand {@link
255      * SecurityManager#checkWrite checkWrite(file.getPath())}
256      * denies write access to the file
257      *
258      * @throws UnsupportedEncodingException
259      * If the named charset is not supported
260      *
261      * @since 1.5
262      */

263     public PrintStream(File JavaDoc file, String JavaDoc csn)
264     throws FileNotFoundException JavaDoc, UnsupportedEncodingException JavaDoc
265     {
266     this(false, new FileOutputStream JavaDoc(file));
267     init(new OutputStreamWriter JavaDoc(this, csn));
268     }
269
270     /** Check to make sure that the stream has not been closed */
271     private void ensureOpen() throws IOException JavaDoc {
272     if (out == null)
273         throw new IOException JavaDoc("Stream closed");
274     }
275
276     /**
277      * Flush the stream. This is done by writing any buffered output bytes to
278      * the underlying output stream and then flushing that stream.
279      *
280      * @see java.io.OutputStream#flush()
281      */

282     public void flush() {
283     synchronized (this) {
284         try {
285         ensureOpen();
286         out.flush();
287         }
288         catch (IOException JavaDoc x) {
289         trouble = true;
290         }
291     }
292     }
293
294     private boolean closing = false; /* To avoid recursive closing */
295
296     /**
297      * Close the stream. This is done by flushing the stream and then closing
298      * the underlying output stream.
299      *
300      * @see java.io.OutputStream#close()
301      */

302     public void close() {
303     synchronized (this) {
304         if (! closing) {
305         closing = true;
306         try {
307             textOut.close();
308             out.close();
309         }
310         catch (IOException JavaDoc x) {
311             trouble = true;
312         }
313         textOut = null;
314         charOut = null;
315         out = null;
316         }
317     }
318     }
319
320     /**
321      * Flush the stream and check its error state. The internal error state
322      * is set to <code>true</code> when the underlying output stream throws an
323      * <code>IOException</code> other than <code>InterruptedIOException</code>,
324      * and when the <code>setError</code> method is invoked. If an operation
325      * on the underlying output stream throws an
326      * <code>InterruptedIOException</code>, then the <code>PrintStream</code>
327      * converts the exception back into an interrupt by doing:
328      * <pre>
329      * Thread.currentThread().interrupt();
330      * </pre>
331      * or the equivalent.
332      *
333      * @return True if and only if this stream has encountered an
334      * <code>IOException</code> other than
335      * <code>InterruptedIOException</code>, or the
336      * <code>setError</code> method has been invoked
337      */

338     public boolean checkError() {
339     if (out != null)
340         flush();
341     return trouble;
342     }
343
344     /**
345      * Set the error state of the stream to <code>true</code>.
346      *
347      * @since JDK1.1
348      */

349     protected void setError() {
350     trouble = true;
351     try {
352         throw new IOException JavaDoc();
353     } catch (IOException JavaDoc x) {
354     }
355     }
356
357
358     /*
359      * Exception-catching, synchronized output operations,
360      * which also implement the write() methods of OutputStream
361      */

362
363     /**
364      * Write the specified byte to this stream. If the byte is a newline and
365      * automatic flushing is enabled then the <code>flush</code> method will be
366      * invoked.
367      *
368      * <p> Note that the byte is written as given; to write a character that
369      * will be translated according to the platform's default character
370      * encoding, use the <code>print(char)</code> or <code>println(char)</code>
371      * methods.
372      *
373      * @param b The byte to be written
374      * @see #print(char)
375      * @see #println(char)
376      */

377     public void write(int b) {
378     try {
379         synchronized (this) {
380         ensureOpen();
381         out.write(b);
382         if ((b == '\n') && autoFlush)
383             out.flush();
384         }
385     }
386     catch (InterruptedIOException JavaDoc x) {
387         Thread.currentThread().interrupt();
388     }
389     catch (IOException JavaDoc x) {
390         trouble = true;
391     }
392     }
393
394     /**
395      * Write <code>len</code> bytes from the specified byte array starting at
396      * offset <code>off</code> to this stream. If automatic flushing is
397      * enabled then the <code>flush</code> method will be invoked.
398      *
399      * <p> Note that the bytes will be written as given; to write characters
400      * that will be translated according to the platform's default character
401      * encoding, use the <code>print(char)</code> or <code>println(char)</code>
402      * methods.
403      *
404      * @param buf A byte array
405      * @param off Offset from which to start taking bytes
406      * @param len Number of bytes to write
407      */

408     public void write(byte buf[], int off, int len) {
409     try {
410         synchronized (this) {
411         ensureOpen();
412         out.write(buf, off, len);
413         if (autoFlush)
414             out.flush();
415         }
416     }
417     catch (InterruptedIOException JavaDoc x) {
418         Thread.currentThread().interrupt();
419     }
420     catch (IOException JavaDoc x) {
421         trouble = true;
422     }
423     }
424
425     /*
426      * The following private methods on the text- and character-output streams
427      * always flush the stream buffers, so that writes to the underlying byte
428      * stream occur as promptly as with the original PrintStream.
429      */

430
431     private void write(char buf[]) {
432     try {
433         synchronized (this) {
434         ensureOpen();
435         textOut.write(buf);
436         textOut.flushBuffer();
437         charOut.flushBuffer();
438         if (autoFlush) {
439             for (int i = 0; i < buf.length; i++)
440             if (buf[i] == '\n')
441                 out.flush();
442         }
443         }
444     }
445     catch (InterruptedIOException JavaDoc x) {
446         Thread.currentThread().interrupt();
447     }
448     catch (IOException JavaDoc x) {
449         trouble = true;
450     }
451     }
452
453     private void write(String JavaDoc s) {
454     try {
455         synchronized (this) {
456         ensureOpen();
457         textOut.write(s);
458         textOut.flushBuffer();
459         charOut.flushBuffer();
460         if (autoFlush && (s.indexOf('\n') >= 0))
461             out.flush();
462         }
463     }
464     catch (InterruptedIOException JavaDoc x) {
465         Thread.currentThread().interrupt();
466     }
467     catch (IOException JavaDoc x) {
468         trouble = true;
469     }
470     }
471
472     private void newLine() {
473     try {
474         synchronized (this) {
475         ensureOpen();
476         textOut.newLine();
477         textOut.flushBuffer();
478         charOut.flushBuffer();
479         if (autoFlush)
480             out.flush();
481         }
482     }
483     catch (InterruptedIOException JavaDoc x) {
484         Thread.currentThread().interrupt();
485     }
486     catch (IOException JavaDoc x) {
487         trouble = true;
488     }
489     }
490
491
492     /* Methods that do not terminate lines */
493
494     /**
495      * Print a boolean value. The string produced by <code>{@link
496      * java.lang.String#valueOf(boolean)}</code> is translated into bytes
497      * according to the platform's default character encoding, and these bytes
498      * are written in exactly the manner of the
499      * <code>{@link #write(int)}</code> method.
500      *
501      * @param b The <code>boolean</code> to be printed
502      */

503     public void print(boolean b) {
504     write(b ? "true" : "false");
505     }
506
507     /**
508      * Print a character. The character is translated into one or more bytes
509      * according to the platform's default character encoding, and these bytes
510      * are written in exactly the manner of the
511      * <code>{@link #write(int)}</code> method.
512      *
513      * @param c The <code>char</code> to be printed
514      */

515     public void print(char c) {
516     write(String.valueOf(c));
517     }
518
519     /**
520      * Print an integer. The string produced by <code>{@link
521      * java.lang.String#valueOf(int)}</code> is translated into bytes
522      * according to the platform's default character encoding, and these bytes
523      * are written in exactly the manner of the
524      * <code>{@link #write(int)}</code> method.
525      *
526      * @param i The <code>int</code> to be printed
527      * @see java.lang.Integer#toString(int)
528      */

529     public void print(int i) {
530     write(String.valueOf(i));
531     }
532
533     /**
534      * Print a long integer. The string produced by <code>{@link
535      * java.lang.String#valueOf(long)}</code> is translated into bytes
536      * according to the platform's default character encoding, and these bytes
537      * are written in exactly the manner of the
538      * <code>{@link #write(int)}</code> method.
539      *
540      * @param l The <code>long</code> to be printed
541      * @see java.lang.Long#toString(long)
542      */

543     public void print(long l) {
544     write(String.valueOf(l));
545     }
546
547     /**
548      * Print a floating-point number. The string produced by <code>{@link
549      * java.lang.String#valueOf(float)}</code> is translated into bytes
550      * according to the platform's default character encoding, and these bytes
551      * are written in exactly the manner of the
552      * <code>{@link #write(int)}</code> method.
553      *
554      * @param f The <code>float</code> to be printed
555      * @see java.lang.Float#toString(float)
556      */

557     public void print(float f) {
558     write(String.valueOf(f));
559     }
560
561     /**
562      * Print a double-precision floating-point number. The string produced by
563      * <code>{@link java.lang.String#valueOf(double)}</code> is translated into
564      * bytes according to the platform's default character encoding, and these
565      * bytes are written in exactly the manner of the <code>{@link
566      * #write(int)}</code> method.
567      *
568      * @param d The <code>double</code> to be printed
569      * @see java.lang.Double#toString(double)
570      */

571     public void print(double d) {
572     write(String.valueOf(d));
573     }
574
575     /**
576      * Print an array of characters. The characters are converted into bytes
577      * according to the platform's default character encoding, and these bytes
578      * are written in exactly the manner of the
579      * <code>{@link #write(int)}</code> method.
580      *
581      * @param s The array of chars to be printed
582      *
583      * @throws NullPointerException If <code>s</code> is <code>null</code>
584      */

585     public void print(char s[]) {
586     write(s);
587     }
588
589     /**
590      * Print a string. If the argument is <code>null</code> then the string
591      * <code>"null"</code> is printed. Otherwise, the string's characters are
592      * converted into bytes according to the platform's default character
593      * encoding, and these bytes are written in exactly the manner of the
594      * <code>{@link #write(int)}</code> method.
595      *
596      * @param s The <code>String</code> to be printed
597      */

598     public void print(String JavaDoc s) {
599     if (s == null) {
600         s = "null";
601     }
602     write(s);
603     }
604
605     /**
606      * Print an object. The string produced by the <code>{@link
607      * java.lang.String#valueOf(Object)}</code> method is translated into bytes
608      * according to the platform's default character encoding, and these bytes
609      * are written in exactly the manner of the
610      * <code>{@link #write(int)}</code> method.
611      *
612      * @param obj The <code>Object</code> to be printed
613      * @see java.lang.Object#toString()
614      */

615     public void print(Object JavaDoc obj) {
616     write(String.valueOf(obj));
617     }
618
619
620     /* Methods that do terminate lines */
621
622     /**
623      * Terminate 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      * Print a boolean and then terminate the line. This method behaves as
634      * though it invokes <code>{@link #print(boolean)}</code> and then
635      * <code>{@link #println()}</code>.
636      *
637      * @param x The <code>boolean</code> to be printed
638      */

639     public void println(boolean x) {
640     synchronized (this) {
641         print(x);
642         newLine();
643     }
644     }
645
646     /**
647      * Print a character and then terminate the line. This method behaves as
648      * though it invokes <code>{@link #print(char)}</code> and then
649      * <code>{@link #println()}</code>.
650      *
651      * @param x The <code>char</code> to be printed.
652      */

653     public void println(char x) {
654     synchronized (this) {
655         print(x);
656         newLine();
657     }
658     }
659
660     /**
661      * Print an integer and then terminate the line. This method behaves as
662      * though it invokes <code>{@link #print(int)}</code> and then
663      * <code>{@link #println()}</code>.
664      *
665      * @param x The <code>int</code> to be printed.
666      */

667     public void println(int x) {
668     synchronized (this) {
669         print(x);
670         newLine();
671     }
672     }
673
674     /**
675      * Print a long and then terminate the line. This method behaves as
676      * though it invokes <code>{@link #print(long)}</code> and then
677      * <code>{@link #println()}</code>.
678      *
679      * @param x a The <code>long</code> to be printed.
680      */

681     public void println(long x) {
682     synchronized (this) {
683         print(x);
684         newLine();
685     }
686     }
687
688     /**
689      * Print a float and then terminate the line. This method behaves as
690      * though it invokes <code>{@link #print(float)}</code> and then
691      * <code>{@link #println()}</code>.
692      *
693      * @param x The <code>float</code> to be printed.
694      */

695     public void println(float x) {
696     synchronized (this) {
697         print(x);
698         newLine();
699     }
700     }
701
702     /**
703      * Print a double and then terminate the line. This method behaves as
704      * though it invokes <code>{@link #print(double)}</code> and then
705      * <code>{@link #println()}</code>.
706      *
707      * @param x The <code>double</code> to be printed.
708      */

709     public void println(double x) {
710     synchronized (this) {
711         print(x);
712         newLine();
713     }
714     }
715
716     /**
717      * Print an array of characters and then terminate the line. This method
718      * behaves as though it invokes <code>{@link #print(char[])}</code> and
719      * then <code>{@link #println()}</code>.
720      *
721      * @param x an array of chars to print.
722      */

723     public void println(char x[]) {
724     synchronized (this) {
725         print(x);
726         newLine();
727     }
728     }
729
730     /**
731      * Print a String and then terminate 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> to be printed.
736      */

737     public void println(String JavaDoc x) {
738     synchronized (this) {
739         print(x);
740         newLine();
741     }
742     }
743
744     /**
745      * Print an Object and then terminate the line. This method behaves as
746      * though it invokes <code>{@link #print(Object)}</code> and then
747      * <code>{@link #println()}</code>.
748      *
749      * @param x The <code>Object</code> to be printed.
750      */

751     public void println(Object JavaDoc x) {
752     synchronized (this) {
753         print(x);
754         newLine();
755     }
756     }
757
758     /**
759      * A convenience method to write a formatted string to this output stream
760      * using the specified format string and arguments.
761      *
762      * <p> An invocation of this method of the form <tt>out.printf(format,
763      * args)</tt> behaves in exactly the same way as the invocation
764      *
765      * <pre>
766      * out.format(format, args) </pre>
767      *
768      * @param format
769      * A format string as described in <a
770      * HREF="../util//Formatter.html#syntax">Format string syntax</a>
771      *
772      * @param args
773      * Arguments referenced by the format specifiers in the format
774      * string. If there are more arguments than format specifiers, the
775      * extra arguments are ignored. The number of arguments is
776      * variable and may be zero. The maximum number of arguments is
777      * limited by the maximum dimension of a Java array as defined by
778      * the <a HREF="http://java.sun.com/docs/books/vmspec/">Java
779      * Virtual Machine Specification</a>. The behaviour on a
780      * <tt>null</tt> argument depends on the <a
781      * HREF="../util/Formatter.html#syntax">conversion</a>.
782      *
783      * @throws IllegalFormatException
784      * If a format string contains an illegal syntax, a format
785      * specifier that is incompatible with the given arguments,
786      * insufficient arguments given the format string, or other
787      * illegal conditions. For specification of all possible
788      * formatting errors, see the <a
789      * HREF="../util/Formatter.html#detail">Details</a> section of the
790      * formatter class specification.
791      *
792      * @throws NullPointerException
793      * If the <tt>format</tt> is <tt>null</tt>
794      *
795      * @return This output stream
796      *
797      * @since 1.5
798      */

799     public PrintStream JavaDoc printf(String JavaDoc format, Object JavaDoc ... args) {
800     return format(format, args);
801     }
802
803     /**
804      * A convenience method to write a formatted string to this output stream
805      * using the specified format string and arguments.
806      *
807      * <p> An invocation of this method of the form <tt>out.printf(l, format,
808      * args)</tt> behaves in exactly the same way as the invocation
809      *
810      * <pre>
811      * out.format(l, format, args) </pre>
812      *
813      * @param l
814      * The {@linkplain java.util.Locale locale} to apply during
815      * formatting. If <tt>l</tt> is <tt>null</tt> then no localization
816      * is applied.
817      *
818      * @param format
819      * A format string as described in <a
820      * HREF="../util/Formatter.html#syntax">Format string syntax</a>
821      *
822      * @param args
823      * Arguments referenced by the format specifiers in the format
824      * string. If there are more arguments than format specifiers, the
825      * extra arguments are ignored. The number of arguments is
826      * variable and may be zero. The maximum number of arguments is
827      * limited by the maximum dimension of a Java array as defined by
828      * the <a HREF="http://java.sun.com/docs/books/vmspec/">Java
829      * Virtual Machine Specification</a>. The behaviour on a
830      * <tt>null</tt> argument depends on the <a
831      * HREF="../util/Formatter.html#syntax">conversion</a>.
832      *
833      * @throws IllegalFormatException
834      * If a format string contains an illegal syntax, a format
835      * specifier that is incompatible with the given arguments,
836      * insufficient arguments given the format string, or other
837      * illegal conditions. For specification of all possible
838      * formatting errors, see the <a
839      * HREF="../util/Formatter.html#detail">Details</a> section of the
840      * formatter class specification.
841      *
842      * @throws NullPointerException
843      * If the <tt>format</tt> is <tt>null</tt>
844      *
845      * @return This output stream
846      *
847      * @since 1.5
848      */

849     public PrintStream JavaDoc printf(Locale JavaDoc l, String JavaDoc format, Object JavaDoc ... args) {
850     return format(l, format, args);
851     }
852
853     /**
854      * Writes a formatted string to this output stream using the specified
855      * format string and arguments.
856      *
857      * <p> The locale always used is the one returned by {@link
858      * java.util.Locale#getDefault() Locale.getDefault()}, regardless of any
859      * previous invocations of other formatting methods on this object.
860      *
861      * @param format
862      * A format string as described in <a
863      * HREF="../util/Formatter.html#syntax">Format string syntax</a>
864      *
865      * @param args
866      * Arguments referenced by the format specifiers in the format
867      * string. If there are more arguments than format specifiers, the
868      * extra arguments are ignored. The number of arguments is
869      * variable and may be zero. The maximum number of arguments is
870      * limited by the maximum dimension of a Java array as defined by
871      * the <a HREF="http://java.sun.com/docs/books/vmspec/">Java
872      * Virtual Machine Specification</a>. The behaviour on a
873      * <tt>null</tt> argument depends on the <a
874      * HREF="../util/Formatter.html#syntax">conversion</a>.
875      *
876      * @throws IllegalFormatException
877      * If a format string contains an illegal syntax, a format
878      * specifier that is incompatible with the given arguments,
879      * insufficient arguments given the format string, or other
880      * illegal conditions. For specification of all possible
881      * formatting errors, see the <a
882      * HREF="../util/Formatter.html#detail">Details</a> section of the
883      * formatter class specification.
884      *
885      * @throws NullPointerException
886      * If the <tt>format</tt> is <tt>null</tt>
887      *
888      * @return This output stream
889      *
890      * @since 1.5
891      */

892     public PrintStream JavaDoc format(String JavaDoc format, Object JavaDoc ... args) {
893     try {
894         synchronized (this) {
895         ensureOpen();
896         if ((formatter == null)
897             || (formatter.locale() != Locale.getDefault()))
898             formatter = new Formatter JavaDoc((Appendable JavaDoc) this);
899         formatter.format(Locale.getDefault(), format, args);
900         }
901     } catch (InterruptedIOException JavaDoc x) {
902         Thread.currentThread().interrupt();
903     } catch (IOException JavaDoc x) {
904         trouble = true;
905     }
906     return this;
907     }
908
909     /**
910      * Writes a formatted string to this output stream using the specified
911      * format string and arguments.
912      *
913      * @param l
914      * The {@linkplain java.util.Locale locale} to apply during
915      * formatting. If <tt>l</tt> is <tt>null</tt> then no localization
916      * is applied.
917      *
918      * @param format
919      * A format string as described in <a
920      * HREF="../util/Formatter.html#syntax">Format string syntax</a>
921      *
922      * @param args
923      * Arguments referenced by the format specifiers in the format
924      * string. If there are more arguments than format specifiers, the
925      * extra arguments are ignored. The number of arguments is
926      * variable and may be zero. The maximum number of arguments is
927      * limited by the maximum dimension of a Java array as defined by
928      * the <a HREF="http://java.sun.com/docs/books/vmspec/">Java
929      * Virtual Machine Specification</a>. The behaviour on a
930      * <tt>null</tt> argument depends on the <a
931      * HREF="../util/Formatter.html#syntax">conversion</a>.
932      *
933      * @throws IllegalFormatException
934      * If a format string contains an illegal syntax, a format
935      * specifier that is incompatible with the given arguments,
936      * insufficient arguments given the format string, or other
937      * illegal conditions. For specification of all possible
938      * formatting errors, see the <a
939      * HREF="../util/Formatter.html#detail">Details</a> section of the
940      * formatter class specification.
941      *
942      * @throws NullPointerException
943      * If the <tt>format</tt> is <tt>null</tt>
944      *
945      * @return This output stream
946      *
947      * @since 1.5
948      */

949     public PrintStream JavaDoc format(Locale JavaDoc l, String JavaDoc format, Object JavaDoc ... args) {
950     try {
951         synchronized (this) {
952         ensureOpen();
953         if ((formatter == null)
954             || (formatter.locale() != l))
955             formatter = new Formatter JavaDoc(this, l);
956         formatter.format(l, format, args);
957         }
958     } catch (InterruptedIOException JavaDoc x) {
959         Thread.currentThread().interrupt();
960     } catch (IOException JavaDoc x) {
961         trouble = true;
962     }
963     return this;
964     }
965
966     /**
967      * Appends the specified character sequence to this output stream.
968      *
969      * <p> An invocation of this method of the form <tt>out.append(csq)</tt>
970      * behaves in exactly the same way as the invocation
971      *
972      * <pre>
973      * out.print(csq.toString()) </pre>
974      *
975      * <p> Depending on the specification of <tt>toString</tt> for the
976      * character sequence <tt>csq</tt>, the entire sequence may not be
977      * appended. appended. For instance, invoking then <tt>toString</tt>
978      * method of a character buffer will return a subsequence whose content
979      * depends upon the buffer's position and limit.
980      *
981      * @param csq
982      * The character sequence to append. If <tt>csq</tt> is
983      * <tt>null</tt>, then the four characters <tt>"null"</tt> are
984      * appended to this output stream.
985      *
986      * @return This character stream
987      *
988      * @since 1.5
989      */

990     public PrintStream JavaDoc append(CharSequence JavaDoc csq) {
991     if (csq == null)
992         print("null");
993     else
994         print(csq.toString());
995         return this;
996     }
997
998     /**
999      * Appends a subsequence of the specified character sequence to this output
1000     * stream.
1001     *
1002     * <p> An invocation of this method of the form <tt>out.append(csq, start,
1003     * end)</tt> when <tt>csq</tt> is not <tt>null</tt>, behaves in
1004     * exactly the same way as the invocation
1005     *
1006     * <pre>
1007     * out.print(csq.subSequence(start, end).toString()) </pre>
1008     *
1009     * @param csq
1010     * The character sequence from which a subsequence will be
1011     * appended. If <tt>csq</tt> is <tt>null</tt>, then characters
1012     * will be appended as if <tt>csq</tt> contained the four
1013     * characters <tt>"null"</tt>.
1014     *
1015     * @param start
1016     * The index of the first character in the subsequence
1017     *
1018     * @param end
1019     * The index of the character following the last character in the
1020     * subsequence
1021     *
1022     * @return This character stream
1023     *
1024     * @throws IndexOutOfBoundsException
1025     * If <tt>start</tt> or <tt>end</tt> are negative, <tt>start</tt>
1026     * is greater than <tt>end</tt>, or <tt>end</tt> is greater than
1027     * <tt>csq.length()</tt>
1028     *
1029     * @since 1.5
1030     */

1031    public PrintStream JavaDoc append(CharSequence JavaDoc csq, int start, int end) {
1032    CharSequence JavaDoc cs = (csq == null ? "null" : csq);
1033    write(cs.subSequence(start, end).toString());
1034        return this;
1035    }
1036    
1037    /**
1038     * Appends the specified character to this output stream.
1039     *
1040     * <p> An invocation of this method of the form <tt>out.append(c)</tt>
1041     * behaves in exactly the same way as the invocation
1042     *
1043     * <pre>
1044     * out.print(c) </pre>
1045     *
1046     * @param c
1047     * The 16-bit character to append
1048     *
1049     * @return This output stream
1050     *
1051     * @since 1.5
1052     */

1053    public PrintStream JavaDoc append(char c) {
1054    print(c);
1055    return this;
1056    }
1057
1058}
1059
Popular Tags