libjava/java/io/Writer.java

   1 /* Writer.java -- Base class for character output streams
   2    Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
   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., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 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
  39 package java.io;
  40
  41 /* Written using "Java Class Libraries", 2nd edition, plus online
  42  * API docs for JDK 1.2 beta from http://www.javasoft.com.
  43  * Status:  Believed complete and correct.
  44  */
  45
  46 /**
  47   * This abstract class forms the base of the hierarchy of classes that
  48   * write output as a stream of chars.  It provides a common set of methods
  49   * for writing chars to stream.  Subclasses implement and/or extend these
  50   * methods to write chars in a particular manner or to a particular
  51   * destination such as a file on disk or network connection.
  52   *
  53   * @author Aaron M. Renn (arenn@urbanophile.com)
  54   * @author Per Bothner <bothner@cygnus.com>
  55   */
  56 public abstract class Writer
  57 {
  58
  59 /*************************************************************************/
  60
  61 /**
  62   * This is the object used to synchronize criticial code sections for
  63   * thread safety.  Subclasses should use this field instead of using
  64   * synchronized methods or explicity synchronizations on <code>this</code>
  65   */
  66 protected Object lock;
  67
  68 /*************************************************************************/
  69
  70 /*
  71  * Constructors
  72  */
  73
  74 /**
  75   * This is the default no-argument constructor for this class.  This method
  76   * will set up the class to synchronize criticial sections on itself.
  77   */
  78 protected
  79 Writer()
  80 {
  81   lock = this;
  82 }
  83
  84 /*************************************************************************/
  85
  86 /**
  87   * This method initializes a <code>Writer</code> that will synchronize
  88   * on the specified <code>Object</code>.
  89   *
  90   * @param obj The <code>Object</code> to use for synchronizing critical
  91   *            sections
  92   */
  93 protected
  94 Writer(Object lock)
  95 {
  96   this.lock = lock;
  97 }
  98
  99 /*************************************************************************/
 100
 101 /*
 102  * Instance Methods
 103  */
 104
 105 /**
 106   * This method forces any data that may have been buffered to be written
 107   * to the underlying output device.  Please note that the host environment
 108   * might perform its own buffering unbeknowst to Java.  In that case, a
 109   * write made (for example, to a disk drive) might be cached in OS
 110   * buffers instead of actually being written to disk.
 111   *
 112   * @exception IOException If an error occurs
 113   */
 114 public abstract void
 115 flush() throws IOException;
 116
 117 /*************************************************************************/
 118
 119 /**
 120   * This method closes the stream.  Any internal or native resources associated
 121   * with this stream are freed.  Any subsequent attempt to access the stream
 122   * might throw an exception.
 123   * <p>
 124   * This method in this class does nothing.
 125   *
 126   * @exception IOException If an error occurs
 127   */
 128 public abstract void
 129 close() throws IOException;
 130
 131 /*************************************************************************/
 132
 133 /**
 134   * This method writes a single char to the output stream.
 135   *
 136   * @param b The char to be written to the output stream, passed as an int
 137   *
 138   * @exception IOException If an error occurs
 139   */
 140 public void
 141 write(int b) throws IOException
 142 {
 143   char[] buf = new char[1];
 144
 145   buf[0] = (char)b;
 146   write(buf, 0, buf.length);
 147 }
 148
 149 /*************************************************************************/
 150
 151 /**
 152   * This method all the writes char from the passed array to the output stream.
 153   * This method is equivalent to <code>write(buf, 0, buf.length)</code> which
 154   * is exactly how it is implemented in this class.
 155   *
 156   * @param buf The array of char to write
 157   *
 158   * @exception IOException If an error occurs
 159   */
 160 public void
 161 write(char[] buf) throws IOException
 162 {
 163   write(buf, 0, buf.length);
 164 }
 165
 166 /*************************************************************************/
 167
 168 /**
 169   * This method writes <code>len</code> char from the specified array
 170   * <code>buf</code> starting at index <code>offset</code> into the array.
 171   * <p>
 172   * Subclasses must provide an implementation of this abstract method.
 173   *
 174   * @param buf The array of char to write from
 175   * @param offset The index into the array to start writing from
 176   * @param len The number of char to write
 177   *
 178   * @exception IOException If an error occurs
 179   */
 180 public abstract void
 181 write(char[] buf, int offset, int len) throws IOException;
 182
 183 /*************************************************************************/
 184
 185 /**
 186   * This method writes all the characters in a <code>String</code> to the
 187   * output.
 188   *
 189   * @param str The <code>String</code> whose chars are to be written.
 190   *
 191   * @param IOException If an error occurs
 192   */
 193 public void
 194 write(String str) throws IOException
 195 {
 196   write(str, 0, str.length());
 197 }
 198
 199 /*************************************************************************/
 200
 201 /**
 202   * This method writes <code>len</code> chars from the <code>String</code>
 203   * starting at position <code>offset</code>.
 204   *
 205   * @param str The <code>String</code> that is to be written
 206   * @param offset The character offset into the <code>String</code> to start
 207   *               writing from
 208   * @param len The number of chars to write
 209   *
 210   * @exception IOException If an error occurs
 211   */
 212 public void
 213 write(String str, int offset, int len) throws IOException
 214 {
 215   // FIXME - for libgcj re-write using native code to not require copied buffer.
 216   char[] buf = new char[len];
 217
 218   str.getChars(offset, offset + len, buf, 0);
 219   write(buf, 0, len);
 220 }
 221
 222 } // class Writer