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:    * This is the underlying <code>Writer</code> we are sending output
  76:    * to
  77:    */
  78:   protected Writer out;
  79: 
  80:   /**
  81:    * This method intializes a new <code>PrintWriter</code> object to write
  82:    * to the specified output sink.  The form of the constructor does not
  83:    * enable auto-flush functionality.
  84:    *
  85:    * @param wr The <code>Writer</code> to write to.
  86:    */
  87:   public PrintWriter(Writer wr)
  88:   {
  89:     super(wr.lock);
  90:     this.out = wr;
  91:   }
  92: 
  93:   /**
  94:    * This method intializes a new <code>PrintWriter</code> object to write
  95:    * to the specified output sink.  This constructor also allows "auto-flush"
  96:    * functionality to be specified where the stream will be flushed after
  97:    * every line is terminated or newline character is written.
  98:    *
  99:    * @param wr The <code>Writer</code> to write to.
 100:    * @param autoflush <code>true</code> to flush the stream after every 
 101:    * line, <code>false</code> otherwise
 102:    */
 103:   public PrintWriter(Writer wr, boolean autoflush)
 104:   {
 105:     super(wr.lock);
 106:     this.out = wr;
 107:     this.autoflush = autoflush;
 108:   }
 109: 
 110:   /**
 111:    * This method initializes a new <code>PrintWriter</code> object to write
 112:    * to the specified <code>OutputStream</code>.  Characters will be converted
 113:    * to chars using the system default encoding.  Auto-flush functionality
 114:    * will not be enabled.
 115:    *
 116:    * @param out The <code>OutputStream</code> to write to
 117:    */
 118:   public PrintWriter(OutputStream out)
 119:   {
 120:     super();
 121:     this.out = new OutputStreamWriter(out);
 122:     this.lock = this.out;
 123:   }
 124: 
 125:   /**
 126:    * This method initializes a new <code>PrintWriter</code> object to write
 127:    * to the specified <code>OutputStream</code>.  Characters will be converted
 128:    * to chars using the system default encoding.  This form of the 
 129:    * constructor allows auto-flush functionality to be enabled if desired
 130:    *
 131:    * @param out The <code>OutputStream</code> to write to
 132:    * @param autoflush <code>true</code> to flush the stream after every 
 133:    * <code>println</code> call, <code>false</code> otherwise.
 134:    */
 135:   public PrintWriter(OutputStream out, boolean autoflush)
 136:   {
 137:     this(out);
 138:     this.autoflush = autoflush;
 139:   }
 140: 
 141:   /**
 142:    * This method can be called by subclasses to indicate that an error
 143:    * has occurred and should be reported by <code>checkError</code>.
 144:    */
 145:   protected void setError()
 146:   {
 147:     error = true;
 148:   }
 149: 
 150:   /**
 151:    * This method checks to see if an error has occurred on this stream.  Note
 152:    * that once an error has occurred, this method will continue to report
 153:    * <code>true</code> forever for this stream.  Before checking for an
 154:    * error condition, this method flushes the stream.
 155:    *
 156:    * @return <code>true</code> if an error has occurred, 
 157:    * <code>false</code> otherwise
 158:    */
 159:   public boolean checkError()
 160:   {
 161:     flush();
 162:     return error;
 163:   }
 164: 
 165:   /**
 166:    * This method flushes any buffered chars to the underlying stream and
 167:    * then flushes that stream as well.
 168:    */
 169:   public void flush()
 170:   {
 171:     try
 172:       {
 173:     out.flush();
 174:       }
 175:     catch (IOException ex)
 176:       {
 177:     error = true;
 178:       }
 179:   }
 180: 
 181:   /**
 182:    * This method closes this stream and all underlying streams.
 183:    */
 184:   public void close()
 185:   {
 186:     try
 187:       {
 188:     out.close();
 189:       }
 190:     catch (IOException ex)
 191:       {
 192:     error = true;
 193:       }
 194:   }
 195: 
 196:   /**
 197:    * This method prints a <code>String</code> to the stream.  The actual
 198:    * value printed depends on the system default encoding.
 199:    *
 200:    * @param str The <code>String</code> to print.
 201:    */
 202:   public void print(String str)
 203:   {
 204:     write(str == null ? "null" : str);
 205:   }
 206: 
 207:   /**
 208:    * This method prints a char to the stream.  The actual value printed is
 209:    * determined by the character encoding in use.
 210:    *
 211:    * @param ch The <code>char</code> value to be printed
 212:    */
 213:   public void print(char ch)
 214:   {
 215:     write((int) ch);
 216:   }
 217: 
 218:   /**
 219:    * This method prints an array of characters to the stream.  The actual
 220:    * value printed depends on the system default encoding.
 221:    *
 222:    * @param charArray The array of characters to print.
 223:    */
 224:   public void print(char[] charArray)
 225:   {
 226:     write(charArray, 0, charArray.length);
 227:   }
 228: 
 229:   /**
 230:    * This methods prints a boolean value to the stream.  <code>true</code>
 231:    * values are printed as "true" and <code>false</code> values are printed
 232:    * as "false".
 233:    *
 234:    * @param bool The <code>boolean</code> value to print
 235:    */
 236:   public void print(boolean bool)
 237:   {
 238:     // We purposely call write() and not print() here.  This preserves
 239:     // compatibility with JDK 1.2.
 240:     write (bool ? "true" : "false");
 241:   }
 242: 
 243:   /**
 244:    * This method prints an integer to the stream.  The value printed is
 245:    * determined using the <code>String.valueOf()</code> method.
 246:    *
 247:    * @param inum The <code>int</code> value to be printed
 248:    */
 249:   public void print(int inum)
 250:   {
 251:     // We purposely call write() and not print() here.  This preserves
 252:     // compatibility with JDK 1.2.
 253:     write(Integer.toString(inum));
 254:   }
 255: 
 256:   /**
 257:    * This method prints a long to the stream.  The value printed is
 258:    * determined using the <code>String.valueOf()</code> method.
 259:    *
 260:    * @param lnum The <code>long</code> value to be printed
 261:    */
 262:   public void print(long lnum)
 263:   {
 264:     // We purposely call write() and not print() here.  This preserves
 265:     // compatibility with JDK 1.2.
 266:     write(Long.toString(lnum));
 267:   }
 268: 
 269:   /**
 270:    * This method prints a float to the stream.  The value printed is
 271:    * determined using the <code>String.valueOf()</code> method.
 272:    *
 273:    * @param fnum The <code>float</code> value to be printed
 274:    */
 275:   public void print(float fnum)
 276:   {
 277:     // We purposely call write() and not print() here.  This preserves
 278:     // compatibility with JDK 1.2.
 279:     write(Float.toString(fnum));
 280:   }
 281: 
 282:   /**
 283:    * This method prints a double to the stream.  The value printed is
 284:    * determined using the <code>String.valueOf()</code> method.
 285:    *
 286:    * @param dnum The <code>double</code> value to be printed
 287:    */
 288:   public void print(double dnum)
 289:   {
 290:     // We purposely call write() and not print() here.  This preserves
 291:     // compatibility with JDK 1.2.
 292:     write(Double.toString(dnum));
 293:   }
 294: 
 295:   /**
 296:    * This method prints an <code>Object</code> to the stream.  The actual
 297:    * value printed is determined by calling the <code>String.valueOf()</code>
 298:    * method.
 299:    *
 300:    * @param obj The <code>Object</code> to print.
 301:    */
 302:   public void print(Object obj)
 303:   {
 304:     // We purposely call write() and not print() here.  This preserves
 305:     // compatibility with JDK 1.2.
 306:     write(obj == null ? "null" : obj.toString());
 307:   }
 308: 
 309:   /**
 310:    * This is the system dependent line separator
 311:    */
 312:   private static final char[] line_separator
 313:     = System.getProperty("line.separator").toCharArray();
 314: 
 315:   /**
 316:    * This method prints a line separator sequence to the stream.  The value
 317:    * printed is determined by the system property <xmp>line.separator</xmp>
 318:    * and is not necessarily the Unix '\n' newline character.
 319:    */
 320:   public void println()
 321:   {
 322:     synchronized (lock)
 323:       {
 324:     try
 325:       {
 326:         write(line_separator, 0, line_separator.length);
 327:         if (autoflush)
 328:           out.flush();
 329:       }
 330:     catch (IOException ex)
 331:       {
 332:         error = true;
 333:       }
 334:       }
 335:   }
 336: 
 337:   /**
 338:    * This methods prints a boolean value to the stream.  <code>true</code>
 339:    * values are printed as "true" and <code>false</code> values are printed
 340:    * as "false".
 341:    *
 342:    * This method prints a line termination sequence after printing the value.
 343:    *
 344:    * @param bool The <code>boolean</code> value to print
 345:    */
 346:   public void println(boolean bool)
 347:   {
 348:     synchronized (lock)
 349:       {
 350:     print(bool);
 351:     println();
 352:       }
 353:   }
 354: 
 355:   /**
 356:    * This method prints an integer to the stream.  The value printed is
 357:    * determined using the <code>String.valueOf()</code> method.
 358:    *
 359:    * This method prints a line termination sequence after printing the value.
 360:    *
 361:    * @param inum The <code>int</code> value to be printed
 362:    */
 363:   public void println(int inum)
 364:   {
 365:     synchronized (lock)
 366:       {
 367:     print(inum);
 368:     println();
 369:       }
 370:   }
 371: 
 372:   /**
 373:    * This method prints a long to the stream.  The value printed is
 374:    * determined using the <code>String.valueOf()</code> method.
 375:    *
 376:    * This method prints a line termination sequence after printing the value.
 377:    *
 378:    * @param lnum The <code>long</code> value to be printed
 379:    */
 380:   public void println(long lnum)
 381:   {
 382:     synchronized (lock)
 383:       {
 384:     print(lnum);
 385:     println();
 386:       }
 387:   }
 388: 
 389:   /**
 390:    * This method prints a float to the stream.  The value printed is
 391:    * determined using the <code>String.valueOf()</code> method.
 392:    *
 393:    * This method prints a line termination sequence after printing the value.
 394:    *
 395:    * @param fnum The <code>float</code> value to be printed
 396:    */
 397:   public void println(float fnum)
 398:   {
 399:     synchronized (lock)
 400:       {
 401:     print(fnum);
 402:     println();
 403:       }
 404:   }
 405: 
 406:   /**
 407:    * This method prints a double to the stream.  The value printed is
 408:    * determined using the <code>String.valueOf()</code> method.
 409:    *
 410:    * This method prints a line termination sequence after printing the value.
 411:    *
 412:    * @param dnum The <code>double</code> value to be printed
 413:    */
 414:   public void println(double dnum)
 415:   {
 416:     synchronized (lock)
 417:       {
 418:     print(dnum);
 419:     println();
 420:       }
 421:   }
 422: 
 423:   /**
 424:    * This method prints an <code>Object</code> to the stream.  The actual
 425:    * value printed is determined by calling the <code>String.valueOf()</code>
 426:    * method.
 427:    *
 428:    * This method prints a line termination sequence after printing the value.
 429:    *
 430:    * @param obj The <code>Object</code> to print.
 431:    */
 432:   public void println(Object obj)
 433:   {
 434:     synchronized (lock)
 435:       {
 436:     print(obj);
 437:     println();
 438:       }
 439:   }
 440: 
 441:   /**
 442:    * This method prints a <code>String</code> to the stream.  The actual
 443:    * value printed depends on the system default encoding.
 444:    *
 445:    * This method prints a line termination sequence after printing the value.
 446:    *
 447:    * @param str The <code>String</code> to print.
 448:    */
 449:   public void println(String str)
 450:   {
 451:     synchronized (lock)
 452:       {
 453:     print(str);
 454:     println();
 455:       }
 456:   }
 457: 
 458:   /**
 459:    * This method prints a char to the stream.  The actual value printed is
 460:    * determined by the character encoding in use.
 461:    *
 462:    * This method prints a line termination sequence after printing the value.
 463:    *
 464:    * @param ch The <code>char</code> value to be printed
 465:    */
 466:   public void println(char ch)
 467:   {
 468:     synchronized (lock)
 469:       {
 470:     print(ch);
 471:     println();
 472:       }
 473:   }
 474: 
 475:   /**
 476:    * This method prints an array of characters to the stream.  The actual
 477:    * value printed depends on the system default encoding.
 478:    *
 479:    * This method prints a line termination sequence after printing the value.
 480:    *
 481:    * @param charArray The array of characters to print.
 482:    */
 483:   public void println(char[] charArray)
 484:   {
 485:     synchronized (lock)
 486:       {
 487:     print(charArray);
 488:     println();
 489:       }
 490:   }
 491: 
 492:   /**
 493:    * This method writes a single char to the stream. 
 494:    * 
 495:    * @param ch The char to be written, passed as a int
 496:    */
 497:   public void write(int ch)
 498:   {
 499:     try
 500:       {
 501:     out.write(ch);
 502:       }
 503:     catch (IOException ex)
 504:       {
 505:     error = true;
 506:       }
 507:   }
 508: 
 509:   /**
 510:    * This method writes <code>count</code> chars from the specified array 
 511:    * starting at index <code>offset</code> into the array.
 512:    *
 513:    * @param charArray The array of chars to write
 514:    * @param offset The index into the array to start writing from
 515:    * @param count The number of chars to write
 516:   */
 517:   public void write(char[] charArray, int offset, int count)
 518:   {
 519:     try
 520:       {
 521:     out.write(charArray, offset, count);
 522:       }
 523:     catch (IOException ex)
 524:       {
 525:     error = true;
 526:       }
 527:   }
 528: 
 529:   /**
 530:    * This method writes <code>count</code> chars from the specified
 531:    * <code>String</code> to the output starting at character position
 532:    * <code>offset</code> into the <code>String</code>
 533:    *
 534:    * @param str The <code>String</code> to write chars from
 535:    * @param offset The offset into the <code>String</code> to start writing from
 536:    * @param count The number of chars to write.
 537:    */
 538:   public void write(String str, int offset, int count)
 539:   {
 540:     try
 541:       {
 542:     out.write(str, offset, count);
 543:       }
 544:     catch (IOException ex)
 545:       {
 546:     error = true;
 547:       }
 548:   }
 549: 
 550:   /**
 551:    * This method write all the chars in the specified array to the output.
 552:    *
 553:    * @param charArray The array of characters to write
 554:    */
 555:   public void write(char[] charArray)
 556:   {
 557:     write(charArray, 0, charArray.length);
 558:   }  
 559: 
 560:   /**
 561:    * This method writes the contents of the specified <code>String</code>
 562:    * to the underlying stream.
 563:    *
 564:    * @param str The <code>String</code> to write
 565:    */
 566:   public void write(String str)
 567:   {
 568:     write(str, 0, str.length());
 569:   }  
 570: }