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