Source for java.io.PrintWriter

   1: /* PrintWriter.java -- prints primitive values and objects to a stream as text
   2:    Copyright (C) 1998, 1999, 2000, 2001, 2005  Free Software Foundation
   3: 
   4: This file is part of GNU Classpath.
   5: 
   6: GNU Classpath is free software; you can redistribute it and/or modify
   7: it under the terms of the GNU General Public License as published by
   8: the Free Software Foundation; either version 2, or (at your option)
   9: any later version.
  10:  
  11: GNU Classpath is distributed in the hope that it will be useful, but
  12: WITHOUT ANY WARRANTY; without even the implied warranty of
  13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14: General Public License for more details.
  15: 
  16: You should have received a copy of the GNU General Public License
  17: along with GNU Classpath; see the file COPYING.  If not, write to the
  18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 USA.
  20: 
  21: Linking this library statically or dynamically with other modules is
  22: making a combined work based on this library.  Thus, the terms and
  23: conditions of the GNU General Public License cover the whole
  24: combination.
  25: 
  26: As a special exception, the copyright holders of this library give you
  27: permission to link this library with independent modules to produce an
  28: executable, regardless of the license terms of these independent
  29: modules, and to copy and distribute the resulting executable under
  30: terms of your choice, provided that you also meet, for each linked
  31: independent module, the terms and conditions of the license of that
  32: module.  An independent module is a module which is not derived from
  33: or based on this library.  If you modify this library, you may extend
  34: this exception to your version of the library, but you are not
  35: obligated to do so.  If you do not wish to do so, delete this
  36: exception statement from your version. */
  37: 
  38: package java.io;
  39: 
  40: import java.util.Locale;
  41: import java.util.Formatter;
  42: 
  43: /* Written using "Java Class Libraries", 2nd edition, plus online
  44:  * API docs for JDK 1.2 beta from http://www.javasoft.com.
  45:  * Status:  Believed complete and correct.
  46:  * However, should use native methods for conversion.
  47:  */
  48: 
  49: /**
  50:  * This class prints Java primitive values and objects to a stream as
  51:  * text.  None of the methods in this class throw an exception.  However,
  52:  * errors can be detected by calling the <code>checkError()</code> method.
  53:  * Additionally, this stream can be designated as "autoflush" when 
  54:  * created so that any writes are automatically flushed to the underlying
  55:  * output sink whenever one of the <code>println</code> methods is
  56:  * called.  (Note that this differs from the <code>PrintStream</code>
  57:  * class which also auto-flushes when it encounters a newline character
  58:  * in the chars written).
  59:  *
  60:  * @author Per Bothner (bothner@cygnus.com)
  61:  * @author Aaron M. Renn (arenn@urbanophile.com)
  62:  * @date April 17, 1998.  
  63:  */
  64: public class PrintWriter extends Writer
  65: {
  66:   /**
  67:    * <code>true</code> if auto-flush is enabled, <code>false</code> otherwise
  68:    */
  69:   private boolean autoflush;
  70: 
  71:   /**
  72:    * This boolean indicates whether or not an error has ever occurred
  73:    * on this stream.
  74:    */
  75:   private boolean error;
  76:   
  77:   /**
  78:    * Indicates whether or not the stream has been closed.
  79:    */
  80:   private boolean closed;
  81: 
  82:   /**
  83:    * This is the underlying <code>Writer</code> we are sending output
  84:    * to
  85:    */
  86:   protected Writer out;
  87: 
  88:   /**
  89:    * This method intializes a new <code>PrintWriter</code> object to write
  90:    * to the specified output sink.  The form of the constructor does not
  91:    * enable auto-flush functionality.
  92:    *
  93:    * @param wr The <code>Writer</code> to write to.
  94:    */
  95:   public PrintWriter(Writer wr)
  96:   {
  97:     super(wr.lock);
  98:     this.out = wr;
  99:   }
 100: 
 101:   /**
 102:    * This method intializes a new <code>PrintWriter</code> object to write
 103:    * to the specified output sink.  This constructor also allows "auto-flush"
 104:    * functionality to be specified where the stream will be flushed after
 105:    * every line is terminated or newline character is written.
 106:    *
 107:    * @param wr The <code>Writer</code> to write to.
 108:    * @param autoflush <code>true</code> to flush the stream after every 
 109:    * line, <code>false</code> otherwise
 110:    */
 111:   public PrintWriter(Writer wr, boolean autoflush)
 112:   {
 113:     super(wr.lock);
 114:     this.out = wr;
 115:     this.autoflush = autoflush;
 116:   }
 117: 
 118:   /**
 119:    * This method initializes a new <code>PrintWriter</code> object to write
 120:    * to the specified <code>OutputStream</code>.  Characters will be converted
 121:    * to chars using the system default encoding.  Auto-flush functionality
 122:    * will not be enabled.
 123:    *
 124:    * @param out The <code>OutputStream</code> to write to
 125:    */
 126:   public PrintWriter(OutputStream out)
 127:   {
 128:     super();
 129:     this.out = new OutputStreamWriter(out);
 130:     this.lock = this.out;
 131:   }
 132: 
 133:   /**
 134:    * This method initializes a new <code>PrintWriter</code> object to write
 135:    * to the specified <code>OutputStream</code>.  Characters will be converted
 136:    * to chars using the system default encoding.  This form of the 
 137:    * constructor allows auto-flush functionality to be enabled if desired
 138:    *
 139:    * @param out The <code>OutputStream</code> to write to
 140:    * @param autoflush <code>true</code> to flush the stream after every 
 141:    * <code>println</code> call, <code>false</code> otherwise.
 142:    */
 143:   public PrintWriter(OutputStream out, boolean autoflush)
 144:   {
 145:     this(out);
 146:     this.autoflush = autoflush;
 147:   }
 148: 
 149:   /**
 150:    * This initializes a new PrintWriter object to write to the specified
 151:    * file.  It creates a FileOutputStream object and wraps it in an
 152:    * OutputStreamWriter using the default encoding.
 153:    * @param file name of the file to write to
 154:    * @throws FileNotFoundException if the file cannot be written or created
 155:    * 
 156:    * @since 1.5
 157:    */
 158:   public PrintWriter(String file) throws FileNotFoundException
 159:   {
 160:     this(new FileOutputStream(file));
 161:   }
 162: 
 163:   /**
 164:    * This initializes a new PrintWriter object to write to the specified
 165:    * file.  It creates a FileOutputStream object and wraps it in an
 166:    * OutputStreamWriter using the specified encoding.
 167:    * @param file name of the file to write to
 168:    * @param enc the encoding to use
 169:    * @throws FileNotFoundException if the file cannot be written or created
 170:    * @throws UnsupportedEncodingException if the encoding is not supported
 171:    * 
 172:    * @since 1.5
 173:    */
 174:   public PrintWriter(String file, String enc) 
 175:     throws FileNotFoundException, UnsupportedEncodingException
 176:   {
 177:     this(new OutputStreamWriter(new FileOutputStream(file), enc));
 178:   }
 179: 
 180:   /**
 181:    * This initializes a new PrintWriter object to write to the specified
 182:    * file.  It creates a FileOutputStream object and wraps it in an
 183:    * OutputStreamWriter using the default encoding.
 184:    * @param file the file to write to
 185:    * @throws FileNotFoundException if the file cannot be written or created
 186:    * 
 187:    * @since 1.5
 188:    */
 189:   public PrintWriter(File file) throws FileNotFoundException
 190:   {
 191:     this(new FileOutputStream(file));
 192:   }
 193: 
 194:   /**
 195:    * This initializes a new PrintWriter object to write to the specified
 196:    * file.  It creates a FileOutputStream object and wraps it in an
 197:    * OutputStreamWriter using the specified encoding.
 198:    * @param file the file to write to
 199:    * @param enc the encoding to use
 200:    * @throws FileNotFoundException if the file cannot be written or created
 201:    * @throws UnsupportedEncodingException if the encoding is not supported
 202:    * 
 203:    * @since 1.5
 204:    */
 205:   public PrintWriter(File file, String enc) 
 206:     throws FileNotFoundException, UnsupportedEncodingException
 207:   {
 208:     this(new OutputStreamWriter(new FileOutputStream(file), enc));
 209:   }
 210: 
 211:   /**
 212:    * This method can be called by subclasses to indicate that an error
 213:    * has occurred and should be reported by <code>checkError</code>.
 214:    */
 215:   protected void setError()
 216:   {
 217:     error = true;
 218:   }
 219: 
 220:   /**
 221:    * This method checks to see if an error has occurred on this stream.  Note
 222:    * that once an error has occurred, this method will continue to report
 223:    * <code>true</code> forever for this stream.  Before checking for an
 224:    * error condition, this method flushes the stream.
 225:    *
 226:    * @return <code>true</code> if an error has occurred, 
 227:    * <code>false</code> otherwise
 228:    */
 229:   public boolean checkError()
 230:   {
 231:     if (! closed)
 232:       flush();
 233:     return error;
 234:   }
 235: 
 236:   /**
 237:    * This method flushes any buffered chars to the underlying stream and
 238:    * then flushes that stream as well.
 239:    */
 240:   public void flush()
 241:   {
 242:     try
 243:       {
 244:     out.flush();
 245:       }
 246:     catch (IOException ex)
 247:       {
 248:     error = true;
 249:       }
 250:   }
 251: 
 252:   /**
 253:    * This method closes this stream and all underlying streams.
 254:    */
 255:   public void close()
 256:   {
 257:     try
 258:       {
 259:         out.close();
 260:         closed = true;
 261:       }
 262:     catch (IOException ex)
 263:       {
 264:     error = true;
 265:       }
 266:   }
 267: 
 268:   /**
 269:    * This method prints a <code>String</code> to the stream.  The actual
 270:    * value printed depends on the system default encoding.
 271:    *
 272:    * @param str The <code>String</code> to print.
 273:    */
 274:   public void print(String str)
 275:   {
 276:     write(str == null ? "null" : str);
 277:   }
 278: 
 279:   /**
 280:    * This method prints a char to the stream.  The actual value printed is
 281:    * determined by the character encoding in use.
 282:    *
 283:    * @param ch The <code>char</code> value to be printed
 284:    */
 285:   public void print(char ch)
 286:   {
 287:     write((int) ch);
 288:   }
 289: 
 290:   /**
 291:    * This method prints an array of characters to the stream.  The actual
 292:    * value printed depends on the system default encoding.
 293:    *
 294:    * @param charArray The array of characters to print.
 295:    */
 296:   public void print(char[] charArray)
 297:   {
 298:     write(charArray, 0, charArray.length);
 299:   }
 300: 
 301:   /**
 302:    * This methods prints a boolean value to the stream.  <code>true</code>
 303:    * values are printed as "true" and <code>false</code> values are printed
 304:    * as "false".
 305:    *
 306:    * @param bool The <code>boolean</code> value to print
 307:    */
 308:   public void print(boolean bool)
 309:   {
 310:     // We purposely call write() and not print() here.  This preserves
 311:     // compatibility with JDK 1.2.
 312:     write (bool ? "true" : "false");
 313:   }
 314: 
 315:   /**
 316:    * This method prints an integer to the stream.  The value printed is
 317:    * determined using the <code>String.valueOf()</code> method.
 318:    *
 319:    * @param inum The <code>int</code> value to be printed
 320:    */
 321:   public void print(int inum)
 322:   {
 323:     // We purposely call write() and not print() here.  This preserves
 324:     // compatibility with JDK 1.2.
 325:     write(Integer.toString(inum));
 326:   }
 327: 
 328:   /**
 329:    * This method prints a long to the stream.  The value printed is
 330:    * determined using the <code>String.valueOf()</code> method.
 331:    *
 332:    * @param lnum The <code>long</code> value to be printed
 333:    */
 334:   public void print(long lnum)
 335:   {
 336:     // We purposely call write() and not print() here.  This preserves
 337:     // compatibility with JDK 1.2.
 338:     write(Long.toString(lnum));
 339:   }
 340: 
 341:   /**
 342:    * This method prints a float to the stream.  The value printed is
 343:    * determined using the <code>String.valueOf()</code> method.
 344:    *
 345:    * @param fnum The <code>float</code> value to be printed
 346:    */
 347:   public void print(float fnum)
 348:   {
 349:     // We purposely call write() and not print() here.  This preserves
 350:     // compatibility with JDK 1.2.
 351:     write(Float.toString(fnum));
 352:   }
 353: 
 354:   /**
 355:    * This method prints a double to the stream.  The value printed is
 356:    * determined using the <code>String.valueOf()</code> method.
 357:    *
 358:    * @param dnum The <code>double</code> value to be printed
 359:    */
 360:   public void print(double dnum)
 361:   {
 362:     // We purposely call write() and not print() here.  This preserves
 363:     // compatibility with JDK 1.2.
 364:     write(Double.toString(dnum));
 365:   }
 366: 
 367:   /**
 368:    * This method prints an <code>Object</code> to the stream.  The actual
 369:    * value printed is determined by calling the <code>String.valueOf()</code>
 370:    * method.
 371:    *
 372:    * @param obj The <code>Object</code> to print.
 373:    */
 374:   public void print(Object obj)
 375:   {
 376:     // We purposely call write() and not print() here.  This preserves
 377:     // compatibility with JDK 1.2.
 378:     write(obj == null ? "null" : obj.toString());
 379:   }
 380: 
 381:   /**
 382:    * This is the system dependent line separator
 383:    */
 384:   private static final char[] line_separator
 385:     = System.getProperty("line.separator", "\n").toCharArray(); 
 386: 
 387:   /**
 388:    * This method prints a line separator sequence to the stream.  The value
 389:    * printed is determined by the system property <xmp>line.separator</xmp>
 390:    * and is not necessarily the Unix '\n' newline character.
 391:    */
 392:   public void println()
 393:   {
 394:     synchronized (lock)
 395:       {
 396:     try
 397:       {
 398:         write(line_separator, 0, line_separator.length);
 399:         if (autoflush)
 400:           out.flush();
 401:       }
 402:     catch (IOException ex)
 403:       {
 404:         error = true;
 405:       }
 406:       }
 407:   }
 408: 
 409:   /**
 410:    * This methods prints a boolean value to the stream.  <code>true</code>
 411:    * values are printed as "true" and <code>false</code> values are printed
 412:    * as "false".
 413:    *
 414:    * This method prints a line termination sequence after printing the value.
 415:    *
 416:    * @param bool The <code>boolean</code> value to print
 417:    */
 418:   public void println(boolean bool)
 419:   {
 420:     synchronized (lock)
 421:       {
 422:     print(bool);
 423:     println();
 424:       }
 425:   }
 426: 
 427:   /**
 428:    * This method prints an integer to the stream.  The value printed is
 429:    * determined using the <code>String.valueOf()</code> method.
 430:    *
 431:    * This method prints a line termination sequence after printing the value.
 432:    *
 433:    * @param inum The <code>int</code> value to be printed
 434:    */
 435:   public void println(int inum)
 436:   {
 437:     synchronized (lock)
 438:       {
 439:     print(inum);
 440:     println();
 441:       }
 442:   }
 443: 
 444:   /**
 445:    * This method prints a long to the stream.  The value printed is
 446:    * determined using the <code>String.valueOf()</code> method.
 447:    *
 448:    * This method prints a line termination sequence after printing the value.
 449:    *
 450:    * @param lnum The <code>long</code> value to be printed
 451:    */
 452:   public void println(long lnum)
 453:   {
 454:     synchronized (lock)
 455:       {
 456:     print(lnum);
 457:     println();
 458:       }
 459:   }
 460: 
 461:   /**
 462:    * This method prints a float to the stream.  The value printed is
 463:    * determined using the <code>String.valueOf()</code> method.
 464:    *
 465:    * This method prints a line termination sequence after printing the value.
 466:    *
 467:    * @param fnum The <code>float</code> value to be printed
 468:    */
 469:   public void println(float fnum)
 470:   {
 471:     synchronized (lock)
 472:       {
 473:     print(fnum);
 474:     println();
 475:       }
 476:   }
 477: 
 478:   /**
 479:    * This method prints a double to the stream.  The value printed is
 480:    * determined using the <code>String.valueOf()</code> method.
 481:    *
 482:    * This method prints a line termination sequence after printing the value.
 483:    *
 484:    * @param dnum The <code>double</code> value to be printed
 485:    */
 486:   public void println(double dnum)
 487:   {
 488:     synchronized (lock)
 489:       {
 490:     print(dnum);
 491:     println();
 492:       }
 493:   }
 494: 
 495:   /**
 496:    * This method prints an <code>Object</code> to the stream.  The actual
 497:    * value printed is determined by calling the <code>String.valueOf()</code>
 498:    * method.
 499:    *
 500:    * This method prints a line termination sequence after printing the value.
 501:    *
 502:    * @param obj The <code>Object</code> to print.
 503:    */
 504:   public void println(Object obj)
 505:   {
 506:     synchronized (lock)
 507:       {
 508:     print(obj);
 509:     println();
 510:       }
 511:   }
 512: 
 513:   /**
 514:    * This method prints a <code>String</code> to the stream.  The actual
 515:    * value printed depends on the system default encoding.
 516:    *
 517:    * This method prints a line termination sequence after printing the value.
 518:    *
 519:    * @param str The <code>String</code> to print.
 520:    */
 521:   public void println(String str)
 522:   {
 523:     synchronized (lock)
 524:       {
 525:     print(str);
 526:     println();
 527:       }
 528:   }
 529: 
 530:   /**
 531:    * This method prints a char to the stream.  The actual value printed is
 532:    * determined by the character encoding in use.
 533:    *
 534:    * This method prints a line termination sequence after printing the value.
 535:    *
 536:    * @param ch The <code>char</code> value to be printed
 537:    */
 538:   public void println(char ch)
 539:   {
 540:     synchronized (lock)
 541:       {
 542:     print(ch);
 543:     println();
 544:       }
 545:   }
 546: 
 547:   /**
 548:    * This method prints an array of characters to the stream.  The actual
 549:    * value printed depends on the system default encoding.
 550:    *
 551:    * This method prints a line termination sequence after printing the value.
 552:    *
 553:    * @param charArray The array of characters to print.
 554:    */
 555:   public void println(char[] charArray)
 556:   {
 557:     synchronized (lock)
 558:       {
 559:     print(charArray);
 560:     println();
 561:       }
 562:   }
 563: 
 564:   /**
 565:    * This method writes a single char to the stream. 
 566:    * 
 567:    * @param ch The char to be written, passed as a int
 568:    */
 569:   public void write(int ch)
 570:   {
 571:     try
 572:       {
 573:     out.write(ch);
 574:       }
 575:     catch (IOException ex)
 576:       {
 577:     error = true;
 578:       }
 579:   }
 580: 
 581:   /**
 582:    * This method writes <code>count</code> chars from the specified array 
 583:    * starting at index <code>offset</code> into the array.
 584:    *
 585:    * @param charArray The array of chars to write
 586:    * @param offset The index into the array to start writing from
 587:    * @param count The number of chars to write
 588:   */
 589:   public void write(char[] charArray, int offset, int count)
 590:   {
 591:     try
 592:       {
 593:     out.write(charArray, offset, count);
 594:       }
 595:     catch (IOException ex)
 596:       {
 597:     error = true;
 598:       }
 599:   }
 600: 
 601:   /**
 602:    * This method writes <code>count</code> chars from the specified
 603:    * <code>String</code> to the output starting at character position
 604:    * <code>offset</code> into the <code>String</code>
 605:    *
 606:    * @param str The <code>String</code> to write chars from
 607:    * @param offset The offset into the <code>String</code> to start writing from
 608:    * @param count The number of chars to write.
 609:    */
 610:   public void write(String str, int offset, int count)
 611:   {
 612:     try
 613:       {
 614:     out.write(str, offset, count);
 615:       }
 616:     catch (IOException ex)
 617:       {
 618:     error = true;
 619:       }
 620:   }
 621: 
 622:   /**
 623:    * This method write all the chars in the specified array to the output.
 624:    *
 625:    * @param charArray The array of characters to write
 626:    */
 627:   public void write(char[] charArray)
 628:   {
 629:     write(charArray, 0, charArray.length);
 630:   }  
 631: 
 632:   /**
 633:    * This method writes the contents of the specified <code>String</code>
 634:    * to the underlying stream.
 635:    *
 636:    * @param str The <code>String</code> to write
 637:    */
 638:   public void write(String str)
 639:   {
 640:     write(str, 0, str.length());
 641:   }  
 642: 
 643:   /** @since 1.5 */
 644:   public PrintWriter append(char c)
 645:   {
 646:     write(c);
 647:     return this;
 648:   }
 649: 
 650:   /** @since 1.5 */
 651:   public PrintWriter append(CharSequence cs)
 652:   {
 653:     write(cs == null ? "null" : cs.toString());
 654:     return this;
 655:   }
 656: 
 657:   /** @since 1.5 */
 658:   public PrintWriter append(CharSequence cs, int start, int end)
 659:   {
 660:     write(cs == null ? "null" : cs.subSequence(start, end).toString());
 661:     return this;
 662:   }
 663: 
 664:   /** @since 1.5 */
 665:   public PrintWriter printf(String format, Object... args)
 666:   {
 667:     return format(format, args);
 668:   }
 669: 
 670:   /** @since 1.5 */
 671:   public PrintWriter printf(Locale locale, String format, Object... args)
 672:   {
 673:     return format(locale, format, args);
 674:   }
 675: 
 676:   /** @since 1.5 */
 677:   public PrintWriter format(String format, Object... args)
 678:   {
 679:     return format(Locale.getDefault(), format, args);
 680:   }
 681: 
 682:   /** @since 1.5 */
 683:   public PrintWriter format(Locale locale, String format, Object... args)
 684:   {
 685:     Formatter f = new Formatter(this, locale);
 686:     f.format(format, args);
 687:     return this;
 688:   }
 689: }