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