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