0001 /*
0002 * Copyright 1996-2006 Sun Microsystems, Inc. All Rights Reserved.
0003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
0004 *
0005 * This code is free software; you can redistribute it and/or modify it
0006 * under the terms of the GNU General Public License version 2 only, as
0007 * published by the Free Software Foundation. Sun designates this
0008 * particular file as subject to the "Classpath" exception as provided
0009 * by Sun in the LICENSE file that accompanied this code.
0010 *
0011 * This code is distributed in the hope that it will be useful, but WITHOUT
0012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
0013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
0014 * version 2 for more details (a copy is included in the LICENSE file that
0015 * accompanied this code).
0016 *
0017 * You should have received a copy of the GNU General Public License version
0018 * 2 along with this work; if not, write to the Free Software Foundation,
0019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
0020 *
0021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
0022 * CA 95054 USA or visit www.sun.com if you need additional information or
0023 * have any questions.
0024 */
0025
0026 package java.io;
0027
0028 import java.util.Formatter;
0029 import java.util.Locale;
0030
0031 /**
0032 * A <code>PrintStream</code> adds functionality to another output stream,
0033 * namely the ability to print representations of various data values
0034 * conveniently. Two other features are provided as well. Unlike other output
0035 * streams, a <code>PrintStream</code> never throws an
0036 * <code>IOException</code>; instead, exceptional situations merely set an
0037 * internal flag that can be tested via the <code>checkError</code> method.
0038 * Optionally, a <code>PrintStream</code> can be created so as to flush
0039 * automatically; this means that the <code>flush</code> method is
0040 * automatically invoked after a byte array is written, one of the
0041 * <code>println</code> methods is invoked, or a newline character or byte
0042 * (<code>'\n'</code>) is written.
0043 *
0044 * <p> All characters printed by a <code>PrintStream</code> are converted into
0045 * bytes using the platform's default character encoding. The <code>{@link
0046 * PrintWriter}</code> class should be used in situations that require writing
0047 * characters rather than bytes.
0048 *
0049 * @version 1.46, 07/05/05
0050 * @author Frank Yellin
0051 * @author Mark Reinhold
0052 * @since JDK1.0
0053 */
0054
0055 public class PrintStream extends FilterOutputStream implements
0056 Appendable, Closeable {
0057
0058 private boolean autoFlush = false;
0059 private boolean trouble = false;
0060 private Formatter formatter;
0061
0062 /**
0063 * Track both the text- and character-output streams, so that their buffers
0064 * can be flushed without flushing the entire stream.
0065 */
0066 private BufferedWriter textOut;
0067 private OutputStreamWriter charOut;
0068
0069 /**
0070 * Creates a new print stream. This stream will not flush automatically.
0071 *
0072 * @param out The output stream to which values and objects will be
0073 * printed
0074 *
0075 * @see java.io.PrintWriter#PrintWriter(java.io.OutputStream)
0076 */
0077 public PrintStream(OutputStream out) {
0078 this (out, false);
0079 }
0080
0081 /* Initialization is factored into a private constructor (note the swapped
0082 * parameters so that this one isn't confused with the public one) and a
0083 * separate init method so that the following two public constructors can
0084 * share code. We use a separate init method so that the constructor that
0085 * takes an encoding will throw an NPE for a null stream before it throws
0086 * an UnsupportedEncodingException for an unsupported encoding.
0087 */
0088
0089 private PrintStream(boolean autoFlush, OutputStream out) {
0090 super (out);
0091 if (out == null)
0092 throw new NullPointerException("Null output stream");
0093 this .autoFlush = autoFlush;
0094 }
0095
0096 private void init(OutputStreamWriter osw) {
0097 this .charOut = osw;
0098 this .textOut = new BufferedWriter(osw);
0099 }
0100
0101 /**
0102 * Creates a new print stream.
0103 *
0104 * @param out The output stream to which values and objects will be
0105 * printed
0106 * @param autoFlush A boolean; if true, the output buffer will be flushed
0107 * whenever a byte array is written, one of the
0108 * <code>println</code> methods is invoked, or a newline
0109 * character or byte (<code>'\n'</code>) is written
0110 *
0111 * @see java.io.PrintWriter#PrintWriter(java.io.OutputStream, boolean)
0112 */
0113 public PrintStream(OutputStream out, boolean autoFlush) {
0114 this (autoFlush, out);
0115 init(new OutputStreamWriter(this ));
0116 }
0117
0118 /**
0119 * Creates a new print stream.
0120 *
0121 * @param out The output stream to which values and objects will be
0122 * printed
0123 * @param autoFlush A boolean; if true, the output buffer will be flushed
0124 * whenever a byte array is written, one of the
0125 * <code>println</code> methods is invoked, or a newline
0126 * character or byte (<code>'\n'</code>) is written
0127 * @param encoding The name of a supported
0128 * <a href="../lang/package-summary.html#charenc">
0129 * character encoding</a>
0130 *
0131 * @throws UnsupportedEncodingException
0132 * If the named encoding is not supported
0133 *
0134 * @since 1.4
0135 */
0136 public PrintStream(OutputStream out, boolean autoFlush,
0137 String encoding) throws UnsupportedEncodingException {
0138 this (autoFlush, out);
0139 init(new OutputStreamWriter(this , encoding));
0140 }
0141
0142 /**
0143 * Creates a new print stream, without automatic line flushing, with the
0144 * specified file name. This convenience constructor creates
0145 * the necessary intermediate {@link java.io.OutputStreamWriter
0146 * OutputStreamWriter}, which will encode characters using the
0147 * {@linkplain java.nio.charset.Charset#defaultCharset() default charset}
0148 * for this instance of the Java virtual machine.
0149 *
0150 * @param fileName
0151 * The name of the file to use as the destination of this print
0152 * stream. If the file exists, then it will be truncated to
0153 * zero size; otherwise, a new file will be created. The output
0154 * will be written to the file and is buffered.
0155 *
0156 * @throws FileNotFoundException
0157 * If the given file object does not denote an existing, writable
0158 * regular file and a new regular file of that name cannot be
0159 * created, or if some other error occurs while opening or
0160 * creating the file
0161 *
0162 * @throws SecurityException
0163 * If a security manager is present and {@link
0164 * SecurityManager#checkWrite checkWrite(fileName)} denies write
0165 * access to the file
0166 *
0167 * @since 1.5
0168 */
0169 public PrintStream(String fileName) throws FileNotFoundException {
0170 this (false, new FileOutputStream(fileName));
0171 init(new OutputStreamWriter(this ));
0172 }
0173
0174 /**
0175 * Creates a new print stream, without automatic line flushing, with the
0176 * specified file name and charset. This convenience constructor creates
0177 * the necessary intermediate {@link java.io.OutputStreamWriter
0178 * OutputStreamWriter}, which will encode characters using the provided
0179 * charset.
0180 *
0181 * @param fileName
0182 * The name of the file to use as the destination of this print
0183 * stream. If the file exists, then it will be truncated to
0184 * zero size; otherwise, a new file will be created. The output
0185 * will be written to the file and is buffered.
0186 *
0187 * @param csn
0188 * The name of a supported {@linkplain java.nio.charset.Charset
0189 * charset}
0190 *
0191 * @throws FileNotFoundException
0192 * If the given file object does not denote an existing, writable
0193 * regular file and a new regular file of that name cannot be
0194 * created, or if some other error occurs while opening or
0195 * creating the file
0196 *
0197 * @throws SecurityException
0198 * If a security manager is present and {@link
0199 * SecurityManager#checkWrite checkWrite(fileName)} denies write
0200 * access to the file
0201 *
0202 * @throws UnsupportedEncodingException
0203 * If the named charset is not supported
0204 *
0205 * @since 1.5
0206 */
0207 public PrintStream(String fileName, String csn)
0208 throws FileNotFoundException, UnsupportedEncodingException {
0209 this (false, new FileOutputStream(fileName));
0210 init(new OutputStreamWriter(this , csn));
0211 }
0212
0213 /**
0214 * Creates a new print stream, without automatic line flushing, with the
0215 * specified file. This convenience constructor creates the necessary
0216 * intermediate {@link java.io.OutputStreamWriter OutputStreamWriter},
0217 * which will encode characters using the {@linkplain
0218 * java.nio.charset.Charset#defaultCharset() default charset} for this
0219 * instance of the Java virtual machine.
0220 *
0221 * @param file
0222 * The file to use as the destination of this print stream. If the
0223 * file exists, then it will be truncated to zero size; otherwise,
0224 * a new file will be created. The output will be written to the
0225 * file and is buffered.
0226 *
0227 * @throws FileNotFoundException
0228 * If the given file object does not denote an existing, writable
0229 * regular file and a new regular file of that name cannot be
0230 * created, or if some other error occurs while opening or
0231 * creating the file
0232 *
0233 * @throws SecurityException
0234 * If a security manager is present and {@link
0235 * SecurityManager#checkWrite checkWrite(file.getPath())}
0236 * denies write access to the file
0237 *
0238 * @since 1.5
0239 */
0240 public PrintStream(File file) throws FileNotFoundException {
0241 this (false, new FileOutputStream(file));
0242 init(new OutputStreamWriter(this ));
0243 }
0244
0245 /**
0246 * Creates a new print stream, without automatic line flushing, with the
0247 * specified file and charset. This convenience constructor creates
0248 * the necessary intermediate {@link java.io.OutputStreamWriter
0249 * OutputStreamWriter}, which will encode characters using the provided
0250 * charset.
0251 *
0252 * @param file
0253 * The file to use as the destination of this print stream. If the
0254 * file exists, then it will be truncated to zero size; otherwise,
0255 * a new file will be created. The output will be written to the
0256 * file and is buffered.
0257 *
0258 * @param csn
0259 * The name of a supported {@linkplain java.nio.charset.Charset
0260 * charset}
0261 *
0262 * @throws FileNotFoundException
0263 * If the given file object does not denote an existing, writable
0264 * regular file and a new regular file of that name cannot be
0265 * created, or if some other error occurs while opening or
0266 * creating the file
0267 *
0268 * @throws SecurityException
0269 * If a security manager is presentand {@link
0270 * SecurityManager#checkWrite checkWrite(file.getPath())}
0271 * denies write access to the file
0272 *
0273 * @throws UnsupportedEncodingException
0274 * If the named charset is not supported
0275 *
0276 * @since 1.5
0277 */
0278 public PrintStream(File file, String csn)
0279 throws FileNotFoundException, UnsupportedEncodingException {
0280 this (false, new FileOutputStream(file));
0281 init(new OutputStreamWriter(this , csn));
0282 }
0283
0284 /** Check to make sure that the stream has not been closed */
0285 private void ensureOpen() throws IOException {
0286 if (out == null)
0287 throw new IOException("Stream closed");
0288 }
0289
0290 /**
0291 * Flushes the stream. This is done by writing any buffered output bytes to
0292 * the underlying output stream and then flushing that stream.
0293 *
0294 * @see java.io.OutputStream#flush()
0295 */
0296 public void flush() {
0297 synchronized (this ) {
0298 try {
0299 ensureOpen();
0300 out.flush();
0301 } catch (IOException x) {
0302 trouble = true;
0303 }
0304 }
0305 }
0306
0307 private boolean closing = false; /* To avoid recursive closing */
0308
0309 /**
0310 * Closes the stream. This is done by flushing the stream and then closing
0311 * the underlying output stream.
0312 *
0313 * @see java.io.OutputStream#close()
0314 */
0315 public void close() {
0316 synchronized (this ) {
0317 if (!closing) {
0318 closing = true;
0319 try {
0320 textOut.close();
0321 out.close();
0322 } catch (IOException x) {
0323 trouble = true;
0324 }
0325 textOut = null;
0326 charOut = null;
0327 out = null;
0328 }
0329 }
0330 }
0331
0332 /**
0333 * Flushes the stream and checks its error state. The internal error state
0334 * is set to <code>true</code> when the underlying output stream throws an
0335 * <code>IOException</code> other than <code>InterruptedIOException</code>,
0336 * and when the <code>setError</code> method is invoked. If an operation
0337 * on the underlying output stream throws an
0338 * <code>InterruptedIOException</code>, then the <code>PrintStream</code>
0339 * converts the exception back into an interrupt by doing:
0340 * <pre>
0341 * Thread.currentThread().interrupt();
0342 * </pre>
0343 * or the equivalent.
0344 *
0345 * @return <code>true</code> if and only if this stream has encountered an
0346 * <code>IOException</code> other than
0347 * <code>InterruptedIOException</code>, or the
0348 * <code>setError</code> method has been invoked
0349 */
0350 public boolean checkError() {
0351 if (out != null)
0352 flush();
0353 if (out instanceof java.io.PrintStream) {
0354 PrintStream ps = (PrintStream) out;
0355 return ps.checkError();
0356 }
0357 return trouble;
0358 }
0359
0360 /**
0361 * Sets the error state of the stream to <code>true</code>.
0362 *
0363 * <p> This method will cause subsequent invocations of {@link
0364 * #checkError()} to return <tt>true</tt> until {@link
0365 * #clearError()} is invoked.
0366 *
0367 * @since JDK1.1
0368 */
0369 protected void setError() {
0370 trouble = true;
0371 }
0372
0373 /**
0374 * Clears the internal error state of this stream.
0375 *
0376 * <p> This method will cause subsequent invocations of {@link
0377 * #checkError()} to return <tt>false</tt> until another write
0378 * operation fails and invokes {@link #setError()}.
0379 *
0380 * @since 1.6
0381 */
0382 protected void clearError() {
0383 trouble = false;
0384 }
0385
0386 /*
0387 * Exception-catching, synchronized output operations,
0388 * which also implement the write() methods of OutputStream
0389 */
0390
0391 /**
0392 * Writes the specified byte to this stream. If the byte is a newline and
0393 * automatic flushing is enabled then the <code>flush</code> method will be
0394 * invoked.
0395 *
0396 * <p> Note that the byte is written as given; to write a character that
0397 * will be translated according to the platform's default character
0398 * encoding, use the <code>print(char)</code> or <code>println(char)</code>
0399 * methods.
0400 *
0401 * @param b The byte to be written
0402 * @see #print(char)
0403 * @see #println(char)
0404 */
0405 public void write(int b) {
0406 try {
0407 synchronized (this ) {
0408 ensureOpen();
0409 out.write(b);
0410 if ((b == '\n') && autoFlush)
0411 out.flush();
0412 }
0413 } catch (InterruptedIOException x) {
0414 Thread.currentThread().interrupt();
0415 } catch (IOException x) {
0416 trouble = true;
0417 }
0418 }
0419
0420 /**
0421 * Writes <code>len</code> bytes from the specified byte array starting at
0422 * offset <code>off</code> to this stream. If automatic flushing is
0423 * enabled then the <code>flush</code> method will be invoked.
0424 *
0425 * <p> Note that the bytes will be written as given; to write characters
0426 * that will be translated according to the platform's default character
0427 * encoding, use the <code>print(char)</code> or <code>println(char)</code>
0428 * methods.
0429 *
0430 * @param buf A byte array
0431 * @param off Offset from which to start taking bytes
0432 * @param len Number of bytes to write
0433 */
0434 public void write(byte buf[], int off, int len) {
0435 try {
0436 synchronized (this ) {
0437 ensureOpen();
0438 out.write(buf, off, len);
0439 if (autoFlush)
0440 out.flush();
0441 }
0442 } catch (InterruptedIOException x) {
0443 Thread.currentThread().interrupt();
0444 } catch (IOException x) {
0445 trouble = true;
0446 }
0447 }
0448
0449 /*
0450 * The following private methods on the text- and character-output streams
0451 * always flush the stream buffers, so that writes to the underlying byte
0452 * stream occur as promptly as with the original PrintStream.
0453 */
0454
0455 private void write(char buf[]) {
0456 try {
0457 synchronized (this ) {
0458 ensureOpen();
0459 textOut.write(buf);
0460 textOut.flushBuffer();
0461 charOut.flushBuffer();
0462 if (autoFlush) {
0463 for (int i = 0; i < buf.length; i++)
0464 if (buf[i] == '\n')
0465 out.flush();
0466 }
0467 }
0468 } catch (InterruptedIOException x) {
0469 Thread.currentThread().interrupt();
0470 } catch (IOException x) {
0471 trouble = true;
0472 }
0473 }
0474
0475 private void write(String s) {
0476 try {
0477 synchronized (this ) {
0478 ensureOpen();
0479 textOut.write(s);
0480 textOut.flushBuffer();
0481 charOut.flushBuffer();
0482 if (autoFlush && (s.indexOf('\n') >= 0))
0483 out.flush();
0484 }
0485 } catch (InterruptedIOException x) {
0486 Thread.currentThread().interrupt();
0487 } catch (IOException x) {
0488 trouble = true;
0489 }
0490 }
0491
0492 private void newLine() {
0493 try {
0494 synchronized (this ) {
0495 ensureOpen();
0496 textOut.newLine();
0497 textOut.flushBuffer();
0498 charOut.flushBuffer();
0499 if (autoFlush)
0500 out.flush();
0501 }
0502 } catch (InterruptedIOException x) {
0503 Thread.currentThread().interrupt();
0504 } catch (IOException x) {
0505 trouble = true;
0506 }
0507 }
0508
0509 /* Methods that do not terminate lines */
0510
0511 /**
0512 * Prints a boolean value. The string produced by <code>{@link
0513 * java.lang.String#valueOf(boolean)}</code> is translated into bytes
0514 * according to the platform's default character encoding, and these bytes
0515 * are written in exactly the manner of the
0516 * <code>{@link #write(int)}</code> method.
0517 *
0518 * @param b The <code>boolean</code> to be printed
0519 */
0520 public void print(boolean b) {
0521 write(b ? "true" : "false");
0522 }
0523
0524 /**
0525 * Prints a character. The character is translated into one or more bytes
0526 * according to the platform's default character encoding, and these bytes
0527 * are written in exactly the manner of the
0528 * <code>{@link #write(int)}</code> method.
0529 *
0530 * @param c The <code>char</code> to be printed
0531 */
0532 public void print(char c) {
0533 write(String.valueOf(c));
0534 }
0535
0536 /**
0537 * Prints an integer. The string produced by <code>{@link
0538 * java.lang.String#valueOf(int)}</code> is translated into bytes
0539 * according to the platform's default character encoding, and these bytes
0540 * are written in exactly the manner of the
0541 * <code>{@link #write(int)}</code> method.
0542 *
0543 * @param i The <code>int</code> to be printed
0544 * @see java.lang.Integer#toString(int)
0545 */
0546 public void print(int i) {
0547 write(String.valueOf(i));
0548 }
0549
0550 /**
0551 * Prints a long integer. The string produced by <code>{@link
0552 * java.lang.String#valueOf(long)}</code> is translated into bytes
0553 * according to the platform's default character encoding, and these bytes
0554 * are written in exactly the manner of the
0555 * <code>{@link #write(int)}</code> method.
0556 *
0557 * @param l The <code>long</code> to be printed
0558 * @see java.lang.Long#toString(long)
0559 */
0560 public void print(long l) {
0561 write(String.valueOf(l));
0562 }
0563
0564 /**
0565 * Prints a floating-point number. The string produced by <code>{@link
0566 * java.lang.String#valueOf(float)}</code> is translated into bytes
0567 * according to the platform's default character encoding, and these bytes
0568 * are written in exactly the manner of the
0569 * <code>{@link #write(int)}</code> method.
0570 *
0571 * @param f The <code>float</code> to be printed
0572 * @see java.lang.Float#toString(float)
0573 */
0574 public void print(float f) {
0575 write(String.valueOf(f));
0576 }
0577
0578 /**
0579 * Prints a double-precision floating-point number. The string produced by
0580 * <code>{@link java.lang.String#valueOf(double)}</code> is translated into
0581 * bytes according to the platform's default character encoding, and these
0582 * bytes are written in exactly the manner of the <code>{@link
0583 * #write(int)}</code> method.
0584 *
0585 * @param d The <code>double</code> to be printed
0586 * @see java.lang.Double#toString(double)
0587 */
0588 public void print(double d) {
0589 write(String.valueOf(d));
0590 }
0591
0592 /**
0593 * Prints an array of characters. The characters are converted into bytes
0594 * according to the platform's default character encoding, and these bytes
0595 * are written in exactly the manner of the
0596 * <code>{@link #write(int)}</code> method.
0597 *
0598 * @param s The array of chars to be printed
0599 *
0600 * @throws NullPointerException If <code>s</code> is <code>null</code>
0601 */
0602 public void print(char s[]) {
0603 write(s);
0604 }
0605
0606 /**
0607 * Prints a string. If the argument is <code>null</code> then the string
0608 * <code>"null"</code> is printed. Otherwise, the string's characters are
0609 * converted into bytes according to the platform's default character
0610 * encoding, and these bytes are written in exactly the manner of the
0611 * <code>{@link #write(int)}</code> method.
0612 *
0613 * @param s The <code>String</code> to be printed
0614 */
0615 public void print(String s) {
0616 if (s == null) {
0617 s = "null";
0618 }
0619 write(s);
0620 }
0621
0622 /**
0623 * Prints an object. The string produced by the <code>{@link
0624 * java.lang.String#valueOf(Object)}</code> method is translated into bytes
0625 * according to the platform's default character encoding, and these bytes
0626 * are written in exactly the manner of the
0627 * <code>{@link #write(int)}</code> method.
0628 *
0629 * @param obj The <code>Object</code> to be printed
0630 * @see java.lang.Object#toString()
0631 */
0632 public void print(Object obj) {
0633 write(String.valueOf(obj));
0634 }
0635
0636 /* Methods that do terminate lines */
0637
0638 /**
0639 * Terminates the current line by writing the line separator string. The
0640 * line separator string is defined by the system property
0641 * <code>line.separator</code>, and is not necessarily a single newline
0642 * character (<code>'\n'</code>).
0643 */
0644 public void println() {
0645 newLine();
0646 }
0647
0648 /**
0649 * Prints a boolean and then terminate the line. This method behaves as
0650 * though it invokes <code>{@link #print(boolean)}</code> and then
0651 * <code>{@link #println()}</code>.
0652 *
0653 * @param x The <code>boolean</code> to be printed
0654 */
0655 public void println(boolean x) {
0656 synchronized (this ) {
0657 print(x);
0658 newLine();
0659 }
0660 }
0661
0662 /**
0663 * Prints a character and then terminate the line. This method behaves as
0664 * though it invokes <code>{@link #print(char)}</code> and then
0665 * <code>{@link #println()}</code>.
0666 *
0667 * @param x The <code>char</code> to be printed.
0668 */
0669 public void println(char x) {
0670 synchronized (this ) {
0671 print(x);
0672 newLine();
0673 }
0674 }
0675
0676 /**
0677 * Prints an integer and then terminate the line. This method behaves as
0678 * though it invokes <code>{@link #print(int)}</code> and then
0679 * <code>{@link #println()}</code>.
0680 *
0681 * @param x The <code>int</code> to be printed.
0682 */
0683 public void println(int x) {
0684 synchronized (this ) {
0685 print(x);
0686 newLine();
0687 }
0688 }
0689
0690 /**
0691 * Prints a long and then terminate the line. This method behaves as
0692 * though it invokes <code>{@link #print(long)}</code> and then
0693 * <code>{@link #println()}</code>.
0694 *
0695 * @param x a The <code>long</code> to be printed.
0696 */
0697 public void println(long x) {
0698 synchronized (this ) {
0699 print(x);
0700 newLine();
0701 }
0702 }
0703
0704 /**
0705 * Prints a float and then terminate the line. This method behaves as
0706 * though it invokes <code>{@link #print(float)}</code> and then
0707 * <code>{@link #println()}</code>.
0708 *
0709 * @param x The <code>float</code> to be printed.
0710 */
0711 public void println(float x) {
0712 synchronized (this ) {
0713 print(x);
0714 newLine();
0715 }
0716 }
0717
0718 /**
0719 * Prints a double and then terminate the line. This method behaves as
0720 * though it invokes <code>{@link #print(double)}</code> and then
0721 * <code>{@link #println()}</code>.
0722 *
0723 * @param x The <code>double</code> to be printed.
0724 */
0725 public void println(double x) {
0726 synchronized (this ) {
0727 print(x);
0728 newLine();
0729 }
0730 }
0731
0732 /**
0733 * Prints an array of characters and then terminate the line. This method
0734 * behaves as though it invokes <code>{@link #print(char[])}</code> and
0735 * then <code>{@link #println()}</code>.
0736 *
0737 * @param x an array of chars to print.
0738 */
0739 public void println(char x[]) {
0740 synchronized (this ) {
0741 print(x);
0742 newLine();
0743 }
0744 }
0745
0746 /**
0747 * Prints a String and then terminate the line. This method behaves as
0748 * though it invokes <code>{@link #print(String)}</code> and then
0749 * <code>{@link #println()}</code>.
0750 *
0751 * @param x The <code>String</code> to be printed.
0752 */
0753 public void println(String x) {
0754 synchronized (this ) {
0755 print(x);
0756 newLine();
0757 }
0758 }
0759
0760 /**
0761 * Prints an Object and then terminate the line. This method calls
0762 * at first String.valueOf(x) to get the printed object's string value,
0763 * then behaves as
0764 * though it invokes <code>{@link #print(String)}</code> and then
0765 * <code>{@link #println()}</code>.
0766 *
0767 * @param x The <code>Object</code> to be printed.
0768 */
0769 public void println(Object x) {
0770 String s = String.valueOf(x);
0771 synchronized (this ) {
0772 print(s);
0773 newLine();
0774 }
0775 }
0776
0777 /**
0778 * A convenience method to write a formatted string to this output stream
0779 * using the specified format string and arguments.
0780 *
0781 * <p> An invocation of this method of the form <tt>out.printf(format,
0782 * args)</tt> behaves in exactly the same way as the invocation
0783 *
0784 * <pre>
0785 * out.format(format, args) </pre>
0786 *
0787 * @param format
0788 * A format string as described in <a
0789 * href="../util/Formatter.html#syntax">Format string syntax</a>
0790 *
0791 * @param args
0792 * Arguments referenced by the format specifiers in the format
0793 * string. If there are more arguments than format specifiers, the
0794 * extra arguments are ignored. The number of arguments is
0795 * variable and may be zero. The maximum number of arguments is
0796 * limited by the maximum dimension of a Java array as defined by
0797 * the <a href="http://java.sun.com/docs/books/vmspec/">Java
0798 * Virtual Machine Specification</a>. The behaviour on a
0799 * <tt>null</tt> argument depends on the <a
0800 * href="../util/Formatter.html#syntax">conversion</a>.
0801 *
0802 * @throws IllegalFormatException
0803 * If a format string contains an illegal syntax, a format
0804 * specifier that is incompatible with the given arguments,
0805 * insufficient arguments given the format string, or other
0806 * illegal conditions. For specification of all possible
0807 * formatting errors, see the <a
0808 * href="../util/Formatter.html#detail">Details</a> section of the
0809 * formatter class specification.
0810 *
0811 * @throws NullPointerException
0812 * If the <tt>format</tt> is <tt>null</tt>
0813 *
0814 * @return This output stream
0815 *
0816 * @since 1.5
0817 */
0818 public PrintStream printf(String format, Object... args) {
0819 return format(format, args);
0820 }
0821
0822 /**
0823 * A convenience method to write a formatted string to this output stream
0824 * using the specified format string and arguments.
0825 *
0826 * <p> An invocation of this method of the form <tt>out.printf(l, format,
0827 * args)</tt> behaves in exactly the same way as the invocation
0828 *
0829 * <pre>
0830 * out.format(l, format, args) </pre>
0831 *
0832 * @param l
0833 * The {@linkplain java.util.Locale locale} to apply during
0834 * formatting. If <tt>l</tt> is <tt>null</tt> then no localization
0835 * is applied.
0836 *
0837 * @param format
0838 * A format string as described in <a
0839 * href="../util/Formatter.html#syntax">Format string syntax</a>
0840 *
0841 * @param args
0842 * Arguments referenced by the format specifiers in the format
0843 * string. If there are more arguments than format specifiers, the
0844 * extra arguments are ignored. The number of arguments is
0845 * variable and may be zero. The maximum number of arguments is
0846 * limited by the maximum dimension of a Java array as defined by
0847 * the <a href="http://java.sun.com/docs/books/vmspec/">Java
0848 * Virtual Machine Specification</a>. The behaviour on a
0849 * <tt>null</tt> argument depends on the <a
0850 * href="../util/Formatter.html#syntax">conversion</a>.
0851 *
0852 * @throws IllegalFormatException
0853 * If a format string contains an illegal syntax, a format
0854 * specifier that is incompatible with the given arguments,
0855 * insufficient arguments given the format string, or other
0856 * illegal conditions. For specification of all possible
0857 * formatting errors, see the <a
0858 * href="../util/Formatter.html#detail">Details</a> section of the
0859 * formatter class specification.
0860 *
0861 * @throws NullPointerException
0862 * If the <tt>format</tt> is <tt>null</tt>
0863 *
0864 * @return This output stream
0865 *
0866 * @since 1.5
0867 */
0868 public PrintStream printf(Locale l, String format, Object... args) {
0869 return format(l, format, args);
0870 }
0871
0872 /**
0873 * Writes a formatted string to this output stream using the specified
0874 * format string and arguments.
0875 *
0876 * <p> The locale always used is the one returned by {@link
0877 * java.util.Locale#getDefault() Locale.getDefault()}, regardless of any
0878 * previous invocations of other formatting methods on this object.
0879 *
0880 * @param format
0881 * A format string as described in <a
0882 * href="../util/Formatter.html#syntax">Format string syntax</a>
0883 *
0884 * @param args
0885 * Arguments referenced by the format specifiers in the format
0886 * string. If there are more arguments than format specifiers, the
0887 * extra arguments are ignored. The number of arguments is
0888 * variable and may be zero. The maximum number of arguments is
0889 * limited by the maximum dimension of a Java array as defined by
0890 * the <a href="http://java.sun.com/docs/books/vmspec/">Java
0891 * Virtual Machine Specification</a>. The behaviour on a
0892 * <tt>null</tt> argument depends on the <a
0893 * href="../util/Formatter.html#syntax">conversion</a>.
0894 *
0895 * @throws IllegalFormatException
0896 * If a format string contains an illegal syntax, a format
0897 * specifier that is incompatible with the given arguments,
0898 * insufficient arguments given the format string, or other
0899 * illegal conditions. For specification of all possible
0900 * formatting errors, see the <a
0901 * href="../util/Formatter.html#detail">Details</a> section of the
0902 * formatter class specification.
0903 *
0904 * @throws NullPointerException
0905 * If the <tt>format</tt> is <tt>null</tt>
0906 *
0907 * @return This output stream
0908 *
0909 * @since 1.5
0910 */
0911 public PrintStream format(String format, Object... args) {
0912 try {
0913 synchronized (this ) {
0914 ensureOpen();
0915 if ((formatter == null)
0916 || (formatter.locale() != Locale.getDefault()))
0917 formatter = new Formatter((Appendable) this );
0918 formatter.format(Locale.getDefault(), format, args);
0919 }
0920 } catch (InterruptedIOException x) {
0921 Thread.currentThread().interrupt();
0922 } catch (IOException x) {
0923 trouble = true;
0924 }
0925 return this ;
0926 }
0927
0928 /**
0929 * Writes a formatted string to this output stream using the specified
0930 * format string and arguments.
0931 *
0932 * @param l
0933 * The {@linkplain java.util.Locale locale} to apply during
0934 * formatting. If <tt>l</tt> is <tt>null</tt> then no localization
0935 * is applied.
0936 *
0937 * @param format
0938 * A format string as described in <a
0939 * href="../util/Formatter.html#syntax">Format string syntax</a>
0940 *
0941 * @param args
0942 * Arguments referenced by the format specifiers in the format
0943 * string. If there are more arguments than format specifiers, the
0944 * extra arguments are ignored. The number of arguments is
0945 * variable and may be zero. The maximum number of arguments is
0946 * limited by the maximum dimension of a Java array as defined by
0947 * the <a href="http://java.sun.com/docs/books/vmspec/">Java
0948 * Virtual Machine Specification</a>. The behaviour on a
0949 * <tt>null</tt> argument depends on the <a
0950 * href="../util/Formatter.html#syntax">conversion</a>.
0951 *
0952 * @throws IllegalFormatException
0953 * If a format string contains an illegal syntax, a format
0954 * specifier that is incompatible with the given arguments,
0955 * insufficient arguments given the format string, or other
0956 * illegal conditions. For specification of all possible
0957 * formatting errors, see the <a
0958 * href="../util/Formatter.html#detail">Details</a> section of the
0959 * formatter class specification.
0960 *
0961 * @throws NullPointerException
0962 * If the <tt>format</tt> is <tt>null</tt>
0963 *
0964 * @return This output stream
0965 *
0966 * @since 1.5
0967 */
0968 public PrintStream format(Locale l, String format, Object... args) {
0969 try {
0970 synchronized (this ) {
0971 ensureOpen();
0972 if ((formatter == null) || (formatter.locale() != l))
0973 formatter = new Formatter(this , l);
0974 formatter.format(l, format, args);
0975 }
0976 } catch (InterruptedIOException x) {
0977 Thread.currentThread().interrupt();
0978 } catch (IOException x) {
0979 trouble = true;
0980 }
0981 return this ;
0982 }
0983
0984 /**
0985 * Appends the specified character sequence to this output stream.
0986 *
0987 * <p> An invocation of this method of the form <tt>out.append(csq)</tt>
0988 * behaves in exactly the same way as the invocation
0989 *
0990 * <pre>
0991 * out.print(csq.toString()) </pre>
0992 *
0993 * <p> Depending on the specification of <tt>toString</tt> for the
0994 * character sequence <tt>csq</tt>, the entire sequence may not be
0995 * appended. For instance, invoking then <tt>toString</tt> method of a
0996 * character buffer will return a subsequence whose content depends upon
0997 * the buffer's position and limit.
0998 *
0999 * @param csq
1000 * The character sequence to append. If <tt>csq</tt> is
1001 * <tt>null</tt>, then the four characters <tt>"null"</tt> are
1002 * appended to this output stream.
1003 *
1004 * @return This output stream
1005 *
1006 * @since 1.5
1007 */
1008 public PrintStream append(CharSequence csq) {
1009 if (csq == null)
1010 print("null");
1011 else
1012 print(csq.toString());
1013 return this ;
1014 }
1015
1016 /**
1017 * Appends a subsequence of the specified character sequence to this output
1018 * stream.
1019 *
1020 * <p> An invocation of this method of the form <tt>out.append(csq, start,
1021 * end)</tt> when <tt>csq</tt> is not <tt>null</tt>, behaves in
1022 * exactly the same way as the invocation
1023 *
1024 * <pre>
1025 * out.print(csq.subSequence(start, end).toString()) </pre>
1026 *
1027 * @param csq
1028 * The character sequence from which a subsequence will be
1029 * appended. If <tt>csq</tt> is <tt>null</tt>, then characters
1030 * will be appended as if <tt>csq</tt> contained the four
1031 * characters <tt>"null"</tt>.
1032 *
1033 * @param start
1034 * The index of the first character in the subsequence
1035 *
1036 * @param end
1037 * The index of the character following the last character in the
1038 * subsequence
1039 *
1040 * @return This output stream
1041 *
1042 * @throws IndexOutOfBoundsException
1043 * If <tt>start</tt> or <tt>end</tt> are negative, <tt>start</tt>
1044 * is greater than <tt>end</tt>, or <tt>end</tt> is greater than
1045 * <tt>csq.length()</tt>
1046 *
1047 * @since 1.5
1048 */
1049 public PrintStream append(CharSequence csq, int start, int end) {
1050 CharSequence cs = (csq == null ? "null" : csq);
1051 write(cs.subSequence(start, end).toString());
1052 return this ;
1053 }
1054
1055 /**
1056 * Appends the specified character to this output stream.
1057 *
1058 * <p> An invocation of this method of the form <tt>out.append(c)</tt>
1059 * behaves in exactly the same way as the invocation
1060 *
1061 * <pre>
1062 * out.print(c) </pre>
1063 *
1064 * @param c
1065 * The 16-bit character to append
1066 *
1067 * @return This output stream
1068 *
1069 * @since 1.5
1070 */
1071 public PrintStream append(char c) {
1072 print(c);
1073 return this;
1074 }
1075
1076 }
|