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: }
|
