1 /*

     2  * Copyright (c) 1996, 2012, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    25 

    26 package java.io;

    27 

    28 import java.util.Objects;

    29 import java.util.Formatter;

    30 import java.util.Locale;

    31 import java.nio.charset.Charset;

    32 import java.nio.charset.IllegalCharsetNameException;

    33 import java.nio.charset.UnsupportedCharsetException;

    34 

    35 /**

    36  * Prints formatted representations of objects to a text-output stream.  This

    37  * class implements all of the <tt>print</tt> methods found in {@link

    38  * PrintStream}.  It does not contain methods for writing raw bytes, for which

    39  * a program should use unencoded byte streams.

    40  *

    41  * <p> Unlike the {@link PrintStream} class, if automatic flushing is enabled

    42  * it will be done only when one of the <tt>println</tt>, <tt>printf</tt>, or

    43  * <tt>format</tt> methods is invoked, rather than whenever a newline character

    44  * happens to be output.  These methods use the platform's own notion of line

    45  * separator rather than the newline character.

    46  *

    47  * <p> Methods in this class never throw I/O exceptions, although some of its

    48  * constructors may.  The client may inquire as to whether any errors have

    49  * occurred by invoking {@link #checkError checkError()}.

    50  *

    51  * @author      Frank Yellin

    52  * @author      Mark Reinhold

    53  * @since       1.1

    54  */

    55 

    56 public class PrintWriter extends Writer {

    57 

    58     /**

    59      * The underlying character-output stream of this

    60      * <code>PrintWriter</code>.

    61      *

    62      * @since 1.2

    63      */

    64     protected Writer out;

    65 

    66     private final boolean autoFlush;

    67     private boolean trouble = false;

    68     private Formatter formatter;

    69     private PrintStream psOut = null;

    70 

    71     /**

    72      * Line separator string.  This is the value of the line.separator

    73      * property at the moment that the stream was created.

    74      */

    75     private final String lineSeparator;

    76 

    77     /**

    78      * Returns a charset object for the given charset name.

    79      * @throws NullPointerException          is csn is null

    80      * @throws UnsupportedEncodingException  if the charset is not supported

    81      */

    82     private static Charset toCharset(String csn)

    83         throws UnsupportedEncodingException

    84     {

    85         Objects.requireNonNull(csn, "charsetName");

    86         try {

    87             return Charset.forName(csn);

    88         } catch (IllegalCharsetNameException|UnsupportedCharsetException unused) {

    89             // UnsupportedEncodingException should be thrown

    90             throw new UnsupportedEncodingException(csn);

    91         }

    92     }

    93 

    94     /**

    95      * Creates a new PrintWriter, without automatic line flushing.

    96      *

    97      * @param  out        A character-output stream

    98      */

    99     public PrintWriter (Writer out) {

   100         this(out, false);

   101     }

   102 

   103     /**

   104      * Creates a new PrintWriter.

   105      *

   106      * @param  out        A character-output stream

   107      * @param  autoFlush  A boolean; if true, the <tt>println</tt>,

   108      *                    <tt>printf</tt>, or <tt>format</tt> methods will

   109      *                    flush the output buffer

   110      */

   111     public PrintWriter(Writer out,

   112                        boolean autoFlush) {

   113         super(out);

   114         this.out = out;

   115         this.autoFlush = autoFlush;

   116         lineSeparator = java.security.AccessController.doPrivileged(

   117             new sun.security.action.GetPropertyAction("line.separator"));

   118     }

   119 

   120     /**

   121      * Creates a new PrintWriter, without automatic line flushing, from an

   122      * existing OutputStream.  This convenience constructor creates the

   123      * necessary intermediate OutputStreamWriter, which will convert characters

   124      * into bytes using the default character encoding.

   125      *

   126      * @param  out        An output stream

   127      *

   128      * @see java.io.OutputStreamWriter#OutputStreamWriter(java.io.OutputStream)

   129      */

   130     public PrintWriter(OutputStream out) {

   131         this(out, false);

   132     }

   133 

   134     /**

   135      * Creates a new PrintWriter from an existing OutputStream.  This

   136      * convenience constructor creates the necessary intermediate

   137      * OutputStreamWriter, which will convert characters into bytes using the

   138      * default character encoding.

   139      *

   140      * @param  out        An output stream

   141      * @param  autoFlush  A boolean; if true, the <tt>println</tt>,

   142      *                    <tt>printf</tt>, or <tt>format</tt> methods will

   143      *                    flush the output buffer

   144      *

   145      * @see java.io.OutputStreamWriter#OutputStreamWriter(java.io.OutputStream)

   146      */

   147     public PrintWriter(OutputStream out, boolean autoFlush) {

   148         this(new BufferedWriter(new OutputStreamWriter(out)), autoFlush);

   149 

   150         // save print stream for error propagation

   151         if (out instanceof java.io.PrintStream) {

   152             psOut = (PrintStream) out;

   153         }

   154     }

   155 

   156     /**

   157      * Creates a new PrintWriter, without automatic line flushing, with the

   158      * specified file name.  This convenience constructor creates the necessary

   159      * intermediate {@link java.io.OutputStreamWriter OutputStreamWriter},

   160      * which will encode characters using the {@linkplain

   161      * java.nio.charset.Charset#defaultCharset() default charset} for this

   162      * instance of the Java virtual machine.

   163      *

   164      * @param  fileName

   165      *         The name of the file to use as the destination of this writer.

   166      *         If the file exists then it will be truncated to zero size;

   167      *         otherwise, a new file will be created.  The output will be

   168      *         written to the file and is buffered.

   169      *

   170      * @throws  FileNotFoundException

   171      *          If the given string does not denote an existing, writable

   172      *          regular file and a new regular file of that name cannot be

   173      *          created, or if some other error occurs while opening or

   174      *          creating the file

   175      *

   176      * @throws  SecurityException

   177      *          If a security manager is present and {@link

   178      *          SecurityManager#checkWrite checkWrite(fileName)} denies write

   179      *          access to the file

   180      *

   181      * @since  1.5

   182      */

   183     public PrintWriter(String fileName) throws FileNotFoundException {

   184         this(new BufferedWriter(new OutputStreamWriter(new FileOutputStream(fileName))),

   185              false);

   186     }

   187 

   188     /* Private constructor */

   189     private PrintWriter(Charset charset, File file)

   190         throws FileNotFoundException

   191     {

   192         this(new BufferedWriter(new OutputStreamWriter(new FileOutputStream(file), charset)),

   193              false);

   194     }

   195 

   196     /**

   197      * Creates a new PrintWriter, without automatic line flushing, with the

   198      * specified file name and charset.  This convenience constructor creates

   199      * the necessary intermediate {@link java.io.OutputStreamWriter

   200      * OutputStreamWriter}, which will encode characters using the provided

   201      * charset.

   202      *

   203      * @param  fileName

   204      *         The name of the file to use as the destination of this writer.

   205      *         If the file exists then it will be truncated to zero size;

   206      *         otherwise, a new file will be created.  The output will be

   207      *         written to the file and is buffered.

   208      *

   209      * @param  csn

   210      *         The name of a supported {@linkplain java.nio.charset.Charset

   211      *         charset}

   212      *

   213      * @throws  FileNotFoundException

   214      *          If the given string does not denote an existing, writable

   215      *          regular file and a new regular file of that name cannot be

   216      *          created, or if some other error occurs while opening or

   217      *          creating the file

   218      *

   219      * @throws  SecurityException

   220      *          If a security manager is present and {@link

   221      *          SecurityManager#checkWrite checkWrite(fileName)} denies write

   222      *          access to the file

   223      *

   224      * @throws  UnsupportedEncodingException

   225      *          If the named charset is not supported

   226      *

   227      * @since  1.5

   228      */

   229     public PrintWriter(String fileName, String csn)

   230         throws FileNotFoundException, UnsupportedEncodingException

   231     {

   232         this(toCharset(csn), new File(fileName));

   233     }

   234 

   235     /**

   236      * Creates a new PrintWriter, without automatic line flushing, with the

   237      * specified file.  This convenience constructor creates the necessary

   238      * intermediate {@link java.io.OutputStreamWriter OutputStreamWriter},

   239      * which will encode characters using the {@linkplain

   240      * java.nio.charset.Charset#defaultCharset() default charset} for this

   241      * instance of the Java virtual machine.

   242      *

   243      * @param  file

   244      *         The file to use as the destination of this writer.  If the file

   245      *         exists then it will be truncated to zero size; otherwise, a new

   246      *         file will be created.  The output will be written to the file

   247      *         and is buffered.

   248      *

   249      * @throws  FileNotFoundException

   250      *          If the given file object does not denote an existing, writable

   251      *          regular file and a new regular file of that name cannot be

   252      *          created, or if some other error occurs while opening or

   253      *          creating the file

   254      *

   255      * @throws  SecurityException

   256      *          If a security manager is present and {@link

   257      *          SecurityManager#checkWrite checkWrite(file.getPath())}

   258      *          denies write access to the file

   259      *

   260      * @since  1.5

   261      */

   262     public PrintWriter(File file) throws FileNotFoundException {

   263         this(new BufferedWriter(new OutputStreamWriter(new FileOutputStream(file))),

   264              false);

   265     }

   266 

   267     /**

   268      * Creates a new PrintWriter, without automatic line flushing, with the

   269      * specified file and charset.  This convenience constructor creates the

   270      * necessary intermediate {@link java.io.OutputStreamWriter

   271      * OutputStreamWriter}, which will encode characters using the provided

   272      * charset.

   273      *

   274      * @param  file

   275      *         The file to use as the destination of this writer.  If the file

   276      *         exists then it will be truncated to zero size; otherwise, a new

   277      *         file will be created.  The output will be written to the file

   278      *         and is buffered.

   279      *

   280      * @param  csn

   281      *         The name of a supported {@linkplain java.nio.charset.Charset

   282      *         charset}

   283      *

   284      * @throws  FileNotFoundException

   285      *          If the given file object does not denote an existing, writable

   286      *          regular file and a new regular file of that name cannot be

   287      *          created, or if some other error occurs while opening or

   288      *          creating the file

   289      *

   290      * @throws  SecurityException

   291      *          If a security manager is present and {@link

   292      *          SecurityManager#checkWrite checkWrite(file.getPath())}

   293      *          denies write access to the file

   294      *

   295      * @throws  UnsupportedEncodingException

   296      *          If the named charset is not supported

   297      *

   298      * @since  1.5

   299      */

   300     public PrintWriter(File file, String csn)

   301         throws FileNotFoundException, UnsupportedEncodingException

   302     {

   303         this(toCharset(csn), file);

   304     }

   305 

   306     /** Checks to make sure that the stream has not been closed */

   307     private void ensureOpen() throws IOException {

   308         if (out == null)

   309             throw new IOException("Stream closed");

   310     }

   311 

   312     /**

   313      * Flushes the stream.

   314      * @see #checkError()

   315      */

   316     public void flush() {

   317         try {

   318             synchronized (lock) {

   319                 ensureOpen();

   320                 out.flush();

   321             }

   322         }

   323         catch (IOException x) {

   324             trouble = true;

   325         }

   326     }

   327 

   328     /**

   329      * Closes the stream and releases any system resources associated

   330      * with it. Closing a previously closed stream has no effect.

   331      *

   332      * @see #checkError()

   333      */

   334     public void close() {

   335         try {

   336             synchronized (lock) {

   337                 if (out == null)

   338                     return;

   339                 out.close();

   340                 out = null;

   341             }

   342         }

   343         catch (IOException x) {

   344             trouble = true;

   345         }

   346     }

   347 

   348     /**

   349      * Flushes the stream if it's not closed and checks its error state.

   350      *

   351      * @return <code>true</code> if the print stream has encountered an error,

   352      *          either on the underlying output stream or during a format

   353      *          conversion.

   354      */

   355     public boolean checkError() {

   356         if (out != null) {

   357             flush();

   358         }

   359         if (out instanceof java.io.PrintWriter) {

   360             PrintWriter pw = (PrintWriter) out;

   361             return pw.checkError();

   362         } else if (psOut != null) {

   363             return psOut.checkError();

   364         }

   365         return trouble;

   366     }

   367 

   368     /**

   369      * Indicates that an error has occurred.

   370      *

   371      * <p> This method will cause subsequent invocations of {@link

   372      * #checkError()} to return <tt>true</tt> until {@link

   373      * #clearError()} is invoked.

   374      */

   375     protected void setError() {

   376         trouble = true;

   377     }

   378 

   379     /**

   380      * Clears the error state of this stream.

   381      *

   382      * <p> This method will cause subsequent invocations of {@link

   383      * #checkError()} to return <tt>false</tt> until another write

   384      * operation fails and invokes {@link #setError()}.

   385      *

   386      * @since 1.6

   387      */

   388     protected void clearError() {

   389         trouble = false;

   390     }

   391 

   392     /*

   393      * Exception-catching, synchronized output operations,

   394      * which also implement the write() methods of Writer

   395      */

   396 

   397     /**

   398      * Writes a single character.

   399      * @param c int specifying a character to be written.

   400      */

   401     public void write(int c) {

   402         try {

   403             synchronized (lock) {

   404                 ensureOpen();

   405                 out.write(c);

   406             }

   407         }

   408         catch (InterruptedIOException x) {

   409             Thread.currentThread().interrupt();

   410         }

   411         catch (IOException x) {

   412             trouble = true;

   413         }

   414     }

   415 

   416     /**

   417      * Writes A Portion of an array of characters.

   418      * @param buf Array of characters

   419      * @param off Offset from which to start writing characters

   420      * @param len Number of characters to write

   421      */

   422     public void write(char buf[], int off, int len) {

   423         try {

   424             synchronized (lock) {

   425                 ensureOpen();

   426                 out.write(buf, off, len);

   427             }

   428         }

   429         catch (InterruptedIOException x) {

   430             Thread.currentThread().interrupt();

   431         }

   432         catch (IOException x) {

   433             trouble = true;

   434         }

   435     }

   436 

   437     /**

   438      * Writes an array of characters.  This method cannot be inherited from the

   439      * Writer class because it must suppress I/O exceptions.

   440      * @param buf Array of characters to be written

   441      */

   442     public void write(char buf[]) {

   443         write(buf, 0, buf.length);

   444     }

   445 

   446     /**

   447      * Writes a portion of a string.

   448      * @param s A String

   449      * @param off Offset from which to start writing characters

   450      * @param len Number of characters to write

   451      */

   452     public void write(String s, int off, int len) {

   453         try {

   454             synchronized (lock) {

   455                 ensureOpen();

   456                 out.write(s, off, len);

   457             }

   458         }

   459         catch (InterruptedIOException x) {

   460             Thread.currentThread().interrupt();

   461         }

   462         catch (IOException x) {

   463             trouble = true;

   464         }

   465     }

   466 

   467     /**

   468      * Writes a string.  This method cannot be inherited from the Writer class

   469      * because it must suppress I/O exceptions.

   470      * @param s String to be written

   471      */

   472     public void write(String s) {

   473         write(s, 0, s.length());

   474     }

   475 

   476     private void newLine() {

   477         try {

   478             synchronized (lock) {

   479                 ensureOpen();

   480                 out.write(lineSeparator);

   481                 if (autoFlush)

   482                     out.flush();

   483             }

   484         }

   485         catch (InterruptedIOException x) {

   486             Thread.currentThread().interrupt();

   487         }

   488         catch (IOException x) {

   489             trouble = true;

   490         }

   491     }

   492 

   493     /* Methods that do not terminate lines */

   494 

   495     /**

   496      * Prints a boolean value.  The string produced by <code>{@link

   497      * java.lang.String#valueOf(boolean)}</code> is translated into bytes

   498      * according to the platform's default character encoding, and these bytes

   499      * are written in exactly the manner of the <code>{@link

   500      * #write(int)}</code> method.

   501      *

   502      * @param      b   The <code>boolean</code> to be printed

   503      */

   504     public void print(boolean b) {

   505         write(b ? "true" : "false");

   506     }

   507 

   508     /**

   509      * Prints a character.  The character is translated into one or more bytes

   510      * according to the platform's default character encoding, and these bytes

   511      * are written in exactly the manner of the <code>{@link

   512      * #write(int)}</code> method.

   513      *

   514      * @param      c   The <code>char</code> to be printed

   515      */

   516     public void print(char c) {

   517         write(c);

   518     }

   519 

   520     /**

   521      * Prints an integer.  The string produced by <code>{@link

   522      * java.lang.String#valueOf(int)}</code> is translated into bytes according

   523      * to the platform's default character encoding, and these bytes are

   524      * written in exactly the manner of the <code>{@link #write(int)}</code>

   525      * method.

   526      *

   527      * @param      i   The <code>int</code> to be printed

   528      * @see        java.lang.Integer#toString(int)

   529      */

   530     public void print(int i) {

   531         write(String.valueOf(i));

   532     }

   533 

   534     /**

   535      * Prints a long integer.  The string produced by <code>{@link

   536      * java.lang.String#valueOf(long)}</code> is translated into bytes

   537      * according to the platform's default character encoding, and these bytes

   538      * are written in exactly the manner of the <code>{@link #write(int)}</code>

   539      * method.

   540      *

   541      * @param      l   The <code>long</code> to be printed

   542      * @see        java.lang.Long#toString(long)

   543      */

   544     public void print(long l) {

   545         write(String.valueOf(l));

   546     }

   547 

   548     /**

   549      * Prints a floating-point number.  The string produced by <code>{@link

   550      * java.lang.String#valueOf(float)}</code> is translated into bytes

   551      * according to the platform's default character encoding, and these bytes

   552      * are written in exactly the manner of the <code>{@link #write(int)}</code>

   553      * method.

   554      *

   555      * @param      f   The <code>float</code> to be printed

   556      * @see        java.lang.Float#toString(float)

   557      */

   558     public void print(float f) {

   559         write(String.valueOf(f));

   560     }

   561 

   562     /**

   563      * Prints a double-precision floating-point number.  The string produced by

   564      * <code>{@link java.lang.String#valueOf(double)}</code> is translated into

   565      * bytes according to the platform's default character encoding, and these

   566      * bytes are written in exactly the manner of the <code>{@link

   567      * #write(int)}</code> method.

   568      *

   569      * @param      d   The <code>double</code> to be printed

   570      * @see        java.lang.Double#toString(double)

   571      */

   572     public void print(double d) {

   573         write(String.valueOf(d));

   574     }

   575 

   576     /**

   577      * Prints an array of characters.  The characters are converted into bytes

   578      * according to the platform's default character encoding, and these bytes

   579      * are written in exactly the manner of the <code>{@link #write(int)}</code>

   580      * method.

   581      *

   582      * @param      s   The array of chars to be printed

   583      *

   584      * @throws  NullPointerException  If <code>s</code> is <code>null</code>

   585      */

   586     public void print(char s[]) {

   587         write(s);

   588     }

   589 

   590     /**

   591      * Prints a string.  If the argument is <code>null</code> then the string

   592      * <code>"null"</code> is printed.  Otherwise, the string's characters are

   593      * converted into bytes according to the platform's default character

   594      * encoding, and these bytes are written in exactly the manner of the

   595      * <code>{@link #write(int)}</code> method.

   596      *

   597      * @param      s   The <code>String</code> to be printed

   598      */

   599     public void print(String s) {

   600         if (s == null) {

   601             s = "null";

   602         }

   603         write(s);

   604     }

   605 

   606     /**

   607      * Prints an object.  The string produced by the <code>{@link

   608      * java.lang.String#valueOf(Object)}</code> method is translated into bytes

   609      * according to the platform's default character encoding, and these bytes

   610      * are written in exactly the manner of the <code>{@link #write(int)}</code>

   611      * method.

   612      *

   613      * @param      obj   The <code>Object</code> to be printed

   614      * @see        java.lang.Object#toString()

   615      */

   616     public void print(Object obj) {

   617         write(String.valueOf(obj));

   618     }

   619 

   620     /* Methods that do terminate lines */

   621 

   622     /**

   623      * Terminates the current line by writing the line separator string.  The

   624      * line separator string is defined by the system property

   625      * <code>line.separator</code>, and is not necessarily a single newline

   626      * character (<code>'\n'</code>).

   627      */

   628     public void println() {

   629         newLine();

   630     }

   631 

   632     /**

   633      * Prints a boolean value and then terminates the line.  This method behaves

   634      * as though it invokes <code>{@link #print(boolean)}</code> and then

   635      * <code>{@link #println()}</code>.

   636      *

   637      * @param x the <code>boolean</code> value to be printed

   638      */

   639     public void println(boolean x) {

   640         synchronized (lock) {

   641             print(x);

   642             println();

   643         }

   644     }

   645 

   646     /**

   647      * Prints a character and then terminates the line.  This method behaves as

   648      * though it invokes <code>{@link #print(char)}</code> and then <code>{@link

   649      * #println()}</code>.

   650      *

   651      * @param x the <code>char</code> value to be printed

   652      */

   653     public void println(char x) {

   654         synchronized (lock) {

   655             print(x);

   656             println();

   657         }

   658     }

   659 

   660     /**

   661      * Prints an integer and then terminates the line.  This method behaves as

   662      * though it invokes <code>{@link #print(int)}</code> and then <code>{@link

   663      * #println()}</code>.

   664      *

   665      * @param x the <code>int</code> value to be printed

   666      */

   667     public void println(int x) {

   668         synchronized (lock) {

   669             print(x);

   670             println();

   671         }

   672     }

   673 

   674     /**

   675      * Prints a long integer and then terminates the line.  This method behaves

   676      * as though it invokes <code>{@link #print(long)}</code> and then

   677      * <code>{@link #println()}</code>.

   678      *

   679      * @param x the <code>long</code> value to be printed

   680      */

   681     public void println(long x) {

   682         synchronized (lock) {

   683             print(x);

   684             println();

   685         }

   686     }

   687 

   688     /**

   689      * Prints a floating-point number and then terminates the line.  This method

   690      * behaves as though it invokes <code>{@link #print(float)}</code> and then

   691      * <code>{@link #println()}</code>.

   692      *

   693      * @param x the <code>float</code> value to be printed

   694      */

   695     public void println(float x) {

   696         synchronized (lock) {

   697             print(x);

   698             println();

   699         }

   700     }

   701 

   702     /**

   703      * Prints a double-precision floating-point number and then terminates the

   704      * line.  This method behaves as though it invokes <code>{@link

   705      * #print(double)}</code> and then <code>{@link #println()}</code>.

   706      *

   707      * @param x the <code>double</code> value to be printed

   708      */

   709     public void println(double x) {

   710         synchronized (lock) {

   711             print(x);

   712             println();

   713         }

   714     }

   715 

   716     /**

   717      * Prints an array of characters and then terminates the line.  This method

   718      * behaves as though it invokes <code>{@link #print(char[])}</code> and then

   719      * <code>{@link #println()}</code>.

   720      *

   721      * @param x the array of <code>char</code> values to be printed

   722      */

   723     public void println(char x[]) {

   724         synchronized (lock) {

   725             print(x);

   726             println();

   727         }

   728     }

   729 

   730     /**

   731      * Prints a String and then terminates the line.  This method behaves as

   732      * though it invokes <code>{@link #print(String)}</code> and then

   733      * <code>{@link #println()}</code>.

   734      *

   735      * @param x the <code>String</code> value to be printed

   736      */

   737     public void println(String x) {

   738         synchronized (lock) {

   739             print(x);

   740             println();

   741         }

   742     }

   743 

   744     /**

   745      * Prints an Object and then terminates the line.  This method calls

   746      * at first String.valueOf(x) to get the printed object's string value,

   747      * then behaves as

   748      * though it invokes <code>{@link #print(String)}</code> and then

   749      * <code>{@link #println()}</code>.

   750      *

   751      * @param x  The <code>Object</code> to be printed.

   752      */

   753     public void println(Object x) {

   754         String s = String.valueOf(x);

   755         synchronized (lock) {

   756             print(s);

   757             println();

   758         }

   759     }

   760 

   761     /**

   762      * A convenience method to write a formatted string to this writer using

   763      * the specified format string and arguments.  If automatic flushing is

   764      * enabled, calls to this method will flush the output buffer.

   765      *

   766      * <p> An invocation of this method of the form <tt>out.printf(format,

   767      * args)</tt> behaves in exactly the same way as the invocation

   768      *

   769      * <pre>

   770      *     out.format(format, args) </pre>

   771      *

   772      * @param  format

   773      *         A format string as described in <a

   774      *         href="../util/Formatter.html#syntax">Format string syntax</a>.

   775      *

   776      * @param  args

   777      *         Arguments referenced by the format specifiers in the format

   778      *         string.  If there are more arguments than format specifiers, the

   779      *         extra arguments are ignored.  The number of arguments is

   780      *         variable and may be zero.  The maximum number of arguments is

   781      *         limited by the maximum dimension of a Java array as defined by

   782      *         <cite>The Java&trade; Virtual Machine Specification</cite>.

   783      *         The behaviour on a

   784      *         <tt>null</tt> argument depends on the <a

   785      *         href="../util/Formatter.html#syntax">conversion</a>.

   786      *

   787      * @throws  java.util.IllegalFormatException

   788      *          If a format string contains an illegal syntax, a format

   789      *          specifier that is incompatible with the given arguments,

   790      *          insufficient arguments given the format string, or other

   791      *          illegal conditions.  For specification of all possible

   792      *          formatting errors, see the <a

   793      *          href="../util/Formatter.html#detail">Details</a> section of the

   794      *          formatter class specification.

   795      *

   796      * @throws  NullPointerException

   797      *          If the <tt>format</tt> is <tt>null</tt>

   798      *

   799      * @return  This writer

   800      *

   801      * @since  1.5

   802      */

   803     public PrintWriter printf(String format, Object ... args) {

   804         return format(format, args);

   805     }

   806 

   807     /**

   808      * A convenience method to write a formatted string to this writer using

   809      * the specified format string and arguments.  If automatic flushing is

   810      * enabled, calls to this method will flush the output buffer.

   811      *

   812      * <p> An invocation of this method of the form <tt>out.printf(l, format,

   813      * args)</tt> behaves in exactly the same way as the invocation

   814      *

   815      * <pre>

   816      *     out.format(l, format, args) </pre>

   817      *

   818      * @param  l

   819      *         The {@linkplain java.util.Locale locale} to apply during

   820      *         formatting.  If <tt>l</tt> is <tt>null</tt> then no localization

   821      *         is applied.

   822      *

   823      * @param  format

   824      *         A format string as described in <a

   825      *         href="../util/Formatter.html#syntax">Format string syntax</a>.

   826      *

   827      * @param  args

   828      *         Arguments referenced by the format specifiers in the format

   829      *         string.  If there are more arguments than format specifiers, the

   830      *         extra arguments are ignored.  The number of arguments is

   831      *         variable and may be zero.  The maximum number of arguments is

   832      *         limited by the maximum dimension of a Java array as defined by

   833      *         <cite>The Java&trade; Virtual Machine Specification</cite>.

   834      *         The behaviour on a

   835      *         <tt>null</tt> argument depends on the <a

   836      *         href="../util/Formatter.html#syntax">conversion</a>.

   837      *

   838      * @throws  java.util.IllegalFormatException

   839      *          If a format string contains an illegal syntax, a format

   840      *          specifier that is incompatible with the given arguments,

   841      *          insufficient arguments given the format string, or other

   842      *          illegal conditions.  For specification of all possible

   843      *          formatting errors, see the <a

   844      *          href="../util/Formatter.html#detail">Details</a> section of the

   845      *          formatter class specification.

   846      *

   847      * @throws  NullPointerException

   848      *          If the <tt>format</tt> is <tt>null</tt>

   849      *

   850      * @return  This writer

   851      *

   852      * @since  1.5

   853      */

   854     public PrintWriter printf(Locale l, String format, Object ... args) {

   855         return format(l, format, args);

   856     }

   857 

   858     /**

   859      * Writes a formatted string to this writer using the specified format

   860      * string and arguments.  If automatic flushing is enabled, calls to this

   861      * method will flush the output buffer.

   862      *

   863      * <p> The locale always used is the one returned by {@link

   864      * java.util.Locale#getDefault() Locale.getDefault()}, regardless of any

   865      * previous invocations of other formatting methods on this object.

   866      *

   867      * @param  format

   868      *         A format string as described in <a

   869      *         href="../util/Formatter.html#syntax">Format string syntax</a>.

   870      *

   871      * @param  args

   872      *         Arguments referenced by the format specifiers in the format

   873      *         string.  If there are more arguments than format specifiers, the

   874      *         extra arguments are ignored.  The number of arguments is

   875      *         variable and may be zero.  The maximum number of arguments is

   876      *         limited by the maximum dimension of a Java array as defined by

   877      *         <cite>The Java&trade; Virtual Machine Specification</cite>.

   878      *         The behaviour on a

   879      *         <tt>null</tt> argument depends on the <a

   880      *         href="../util/Formatter.html#syntax">conversion</a>.

   881      *

   882      * @throws  java.util.IllegalFormatException

   883      *          If a format string contains an illegal syntax, a format

   884      *          specifier that is incompatible with the given arguments,

   885      *          insufficient arguments given the format string, or other

   886      *          illegal conditions.  For specification of all possible

   887      *          formatting errors, see the <a

   888      *          href="../util/Formatter.html#detail">Details</a> section of the

   889      *          Formatter class specification.

   890      *

   891      * @throws  NullPointerException

   892      *          If the <tt>format</tt> is <tt>null</tt>

   893      *

   894      * @return  This writer

   895      *

   896      * @since  1.5

   897      */

   898     public PrintWriter format(String format, Object ... args) {

   899         try {

   900             synchronized (lock) {

   901                 ensureOpen();

   902                 if ((formatter == null)

   903                     || (formatter.locale() != Locale.getDefault()))

   904                     formatter = new Formatter(this);

   905                 formatter.format(Locale.getDefault(), format, args);

   906                 if (autoFlush)

   907                     out.flush();

   908             }

   909         } catch (InterruptedIOException x) {

   910             Thread.currentThread().interrupt();

   911         } catch (IOException x) {

   912             trouble = true;

   913         }

   914         return this;

   915     }

   916 

   917     /**

   918      * Writes a formatted string to this writer using the specified format

   919      * string and arguments.  If automatic flushing is enabled, calls to this

   920      * method will flush the output buffer.

   921      *

   922      * @param  l

   923      *         The {@linkplain java.util.Locale locale} to apply during

   924      *         formatting.  If <tt>l</tt> is <tt>null</tt> then no localization

   925      *         is applied.

   926      *

   927      * @param  format

   928      *         A format string as described in <a

   929      *         href="../util/Formatter.html#syntax">Format string syntax</a>.

   930      *

   931      * @param  args

   932      *         Arguments referenced by the format specifiers in the format

   933      *         string.  If there are more arguments than format specifiers, the

   934      *         extra arguments are ignored.  The number of arguments is

   935      *         variable and may be zero.  The maximum number of arguments is

   936      *         limited by the maximum dimension of a Java array as defined by

   937      *         <cite>The Java&trade; Virtual Machine Specification</cite>.

   938      *         The behaviour on a

   939      *         <tt>null</tt> argument depends on the <a

   940      *         href="../util/Formatter.html#syntax">conversion</a>.

   941      *

   942      * @throws  java.util.IllegalFormatException

   943      *          If a format string contains an illegal syntax, a format

   944      *          specifier that is incompatible with the given arguments,

   945      *          insufficient arguments given the format string, or other

   946      *          illegal conditions.  For specification of all possible

   947      *          formatting errors, see the <a

   948      *          href="../util/Formatter.html#detail">Details</a> section of the

   949      *          formatter class specification.

   950      *

   951      * @throws  NullPointerException

   952      *          If the <tt>format</tt> is <tt>null</tt>

   953      *

   954      * @return  This writer

   955      *

   956      * @since  1.5

   957      */

   958     public PrintWriter format(Locale l, String format, Object ... args) {

   959         try {

   960             synchronized (lock) {

   961                 ensureOpen();

   962                 if ((formatter == null) || (formatter.locale() != l))

   963                     formatter = new Formatter(this, l);

   964                 formatter.format(l, format, args);

   965                 if (autoFlush)

   966                     out.flush();

   967             }

   968         } catch (InterruptedIOException x) {

   969             Thread.currentThread().interrupt();

   970         } catch (IOException x) {

   971             trouble = true;

   972         }

   973         return this;

   974     }

   975 

   976     /**

   977      * Appends the specified character sequence to this writer.

   978      *

   979      * <p> An invocation of this method of the form <tt>out.append(csq)</tt>

   980      * behaves in exactly the same way as the invocation

   981      *

   982      * <pre>

   983      *     out.write(csq.toString()) </pre>

   984      *

   985      * <p> Depending on the specification of <tt>toString</tt> for the

   986      * character sequence <tt>csq</tt>, the entire sequence may not be

   987      * appended. For instance, invoking the <tt>toString</tt> method of a

   988      * character buffer will return a subsequence whose content depends upon

   989      * the buffer's position and limit.

   990      *

   991      * @param  csq

   992      *         The character sequence to append.  If <tt>csq</tt> is

   993      *         <tt>null</tt>, then the four characters <tt>"null"</tt> are

   994      *         appended to this writer.

   995      *

   996      * @return  This writer

   997      *

   998      * @since  1.5

   999      */

  1000     public PrintWriter append(CharSequence csq) {

  1001         if (csq == null)

  1002             write("null");

  1003         else

  1004             write(csq.toString());

  1005         return this;

  1006     }

  1007 

  1008     /**

  1009      * Appends a subsequence of the specified character sequence to this writer.

  1010      *

  1011      * <p> An invocation of this method of the form <tt>out.append(csq, start,

  1012      * end)</tt> when <tt>csq</tt> is not <tt>null</tt>, behaves in

  1013      * exactly the same way as the invocation

  1014      *

  1015      * <pre>

  1016      *     out.write(csq.subSequence(start, end).toString()) </pre>

  1017      *

  1018      * @param  csq

  1019      *         The character sequence from which a subsequence will be

  1020      *         appended.  If <tt>csq</tt> is <tt>null</tt>, then characters

  1021      *         will be appended as if <tt>csq</tt> contained the four

  1022      *         characters <tt>"null"</tt>.

  1023      *

  1024      * @param  start

  1025      *         The index of the first character in the subsequence

  1026      *

  1027      * @param  end

  1028      *         The index of the character following the last character in the

  1029      *         subsequence

  1030      *

  1031      * @return  This writer

  1032      *

  1033      * @throws  IndexOutOfBoundsException

  1034      *          If <tt>start</tt> or <tt>end</tt> are negative, <tt>start</tt>

  1035      *          is greater than <tt>end</tt>, or <tt>end</tt> is greater than

  1036      *          <tt>csq.length()</tt>

  1037      *

  1038      * @since  1.5

  1039      */

  1040     public PrintWriter append(CharSequence csq, int start, int end) {

  1041         CharSequence cs = (csq == null ? "null" : csq);

  1042         write(cs.subSequence(start, end).toString());

  1043         return this;

  1044     }

  1045 

  1046     /**

  1047      * Appends the specified character to this writer.

  1048      *

  1049      * <p> An invocation of this method of the form <tt>out.append(c)</tt>

  1050      * behaves in exactly the same way as the invocation

  1051      *

  1052      * <pre>

  1053      *     out.write(c) </pre>

  1054      *

  1055      * @param  c

  1056      *         The 16-bit character to append

  1057      *

  1058      * @return  This writer

  1059      *

  1060      * @since 1.5

  1061      */

  1062     public PrintWriter append(char c) {

  1063         write(c);

  1064         return this;

  1065     }

  1066 }