libjava/java/io/InputStreamReader.java

   1 /* InputStreamReader.java -- Reader than transforms bytes to chars
   2    Copyright (C) 1998, 1999, 2001, 2003, 2004, 2005  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 import gnu.gcj.convert.*;
  42
  43 /**
  44  * This class reads characters from a byte input stream.   The characters
  45  * read are converted from bytes in the underlying stream by a
  46  * decoding layer.  The decoding layer transforms bytes to chars according
  47  * to an encoding standard.  There are many available encodings to choose
  48  * from.  The desired encoding can either be specified by name, or if no
  49  * encoding is selected, the system default encoding will be used.  The
  50  * system default encoding name is determined from the system property
  51  * <code>file.encoding</code>.  The only encodings that are guaranteed to
  52  * be availalbe are "8859_1" (the Latin-1 character set) and "UTF8".
  53  * Unforunately, Java does not provide a mechanism for listing the
  54  * ecodings that are supported in a given implementation.
  55  * <p>
  56  * Here is a list of standard encoding names that may be available:
  57  * <p>
  58  * <ul>
  59  * <li>8859_1 (ISO-8859-1/Latin-1)</li>
  60  * <li>8859_2 (ISO-8859-2/Latin-2)</li>
  61  * <li>8859_3 (ISO-8859-3/Latin-3)</li>
  62  * <li>8859_4 (ISO-8859-4/Latin-4)</li>
  63  * <li>8859_5 (ISO-8859-5/Latin-5)</li>
  64  * <li>8859_6 (ISO-8859-6/Latin-6)</li>
  65  * <li>8859_7 (ISO-8859-7/Latin-7)</li>
  66  * <li>8859_8 (ISO-8859-8/Latin-8)</li>
  67  * <li>8859_9 (ISO-8859-9/Latin-9)</li>
  68  * <li>ASCII (7-bit ASCII)</li>
  69  * <li>UTF8 (UCS Transformation Format-8)</li>
  70  * <li>More later</li>
  71  * </ul>
  72  * <p>
  73  * It is recommended that applications do not use
  74  * <code>InputStreamReader</code>'s
  75  * directly.  Rather, for efficiency purposes, an object of this class
  76  * should be wrapped by a <code>BufferedReader</code>.
  77  * <p>
  78  * Due to a deficiency the Java class library design, there is no standard
  79  * way for an application to install its own byte-character encoding.
  80  *
  81  * @see BufferedReader
  82  * @see InputStream
  83  *
  84  * @author Aaron M. Renn (arenn@urbanophile.com)
  85  * @author Per Bothner (bothner@cygnus.com)
  86  * @date April 22, 1998.
  87  */
  88 public class InputStreamReader extends Reader
  89 {
  90   BufferedInputStream in;
  91
  92   // Buffer of chars read from in and converted but not consumed.
  93   char[] work;
  94   // Next available character (in work buffer) to read.
  95   int wpos;
  96   // Last available character (in work buffer) to read.
  97   int wcount;
  98
  99   /*
 100    * This is the byte-character decoder class that does the reading and
 101    * translation of bytes from the underlying stream.
 102    */
 103   BytesToUnicode converter;
 104
 105   /**
 106    * This method initializes a new instance of <code>InputStreamReader</code>
 107    * to read from the specified stream using the default encoding.
 108    *
 109    * @param in The <code>InputStream</code> to read from
 110    */
 111   public InputStreamReader(InputStream in)
 112   {
 113     this(in, BytesToUnicode.getDefaultDecoder());
 114   }
 115
 116   /**
 117    * This method initializes a new instance of <code>InputStreamReader</code>
 118    * to read from the specified stream using a caller supplied character
 119    * encoding scheme.  Note that due to a deficiency in the Java language
 120    * design, there is no way to determine which encodings are supported.
 121    *
 122    * @param in The <code>InputStream</code> to read from
 123    * @param encoding_name The name of the encoding scheme to use
 124    *
 125    * @exception UnsupportedEncodingException If the encoding scheme
 126    * requested is not available.
 127    */
 128   public InputStreamReader(InputStream in, String encoding_name)
 129     throws UnsupportedEncodingException
 130   {
 131     this(in, BytesToUnicode.getDecoder(encoding_name));
 132   }
 133
 134   private InputStreamReader(InputStream in, BytesToUnicode decoder)
 135   {
 136     // FIXME: someone could pass in a BufferedInputStream whose buffer
 137     // is smaller than the longest encoded character for this
 138     // encoding.  We will probably go into an infinite loop in this
 139     // case.  We probably ought to just have our own byte buffering
 140     // here.
 141     this.in = in instanceof BufferedInputStream
 142               ? (BufferedInputStream) in
 143               : new BufferedInputStream(in);
 144     /* Don't need to call super(in) here as long as the lock gets set. */
 145     this.lock = in;
 146     converter = decoder;
 147     converter.setInput(this.in.buf, 0, 0);
 148   }
 149
 150   /**
 151    * This method closes this stream, as well as the underlying
 152    * <code>InputStream</code>.
 153    *
 154    * @exception IOException If an error occurs
 155    */
 156   public void close() throws IOException
 157   {
 158     synchronized (lock)
 159       {
 160         if (in != null)
 161           in.close();
 162         in = null;
 163         work = null;
 164         wpos = wcount = 0;
 165       }
 166   }
 167
 168   /**
 169    * This method returns the name of the encoding that is currently in use
 170    * by this object.  If the stream has been closed, this method is allowed
 171    * to return <code>null</code>.
 172    *
 173    * @return The current encoding name
 174    */
 175   public String getEncoding()
 176   {
 177     return in != null ? converter.getName() : null;
 178   }
 179
 180   /**
 181    * This method checks to see if the stream is read to be read.  It
 182    * will return <code>true</code> if is, or <code>false</code> if it is not.
 183    * If the stream is not ready to be read, it could (although is not required
 184    * to) block on the next read attempt.
 185    *
 186    * @return <code>true</code> if the stream is ready to be read,
 187    * <code>false</code> otherwise
 188    *
 189    * @exception IOException If an error occurs
 190    */
 191   public boolean ready() throws IOException
 192   {
 193     synchronized (lock)
 194       {
 195         if (in == null)
 196           throw new IOException("Stream closed");
 197
 198         if (wpos < wcount)
 199           return true;
 200
 201         // According to the spec, an InputStreamReader is ready if its
 202         // input buffer is not empty (above), or if bytes are
 203         // available on the underlying byte stream.
 204         return in.available () > 0;
 205       }
 206   }
 207
 208   /**
 209    * This method reads up to <code>length</code> characters from the stream into
 210    * the specified array starting at index <code>offset</code> into the
 211    * array.
 212    *
 213    * @param buf The character array to recieve the data read
 214    * @param offset The offset into the array to start storing characters
 215    * @param length The requested number of characters to read.
 216    *
 217    * @return The actual number of characters read, or -1 if end of stream.
 218    *
 219    * @exception IOException If an error occurs
 220    */
 221   public int read (char[] buf, int offset, int length) throws IOException
 222   {
 223     synchronized (lock)
 224       {
 225         if (in == null)
 226           throw new IOException("Stream closed");
 227
 228         if (length == 0)
 229           return 0;
 230
 231         int wavail = wcount - wpos;
 232         if (wavail <= 0)
 233           {
 234             // Nothing waiting, so refill their buffer.
 235             return refill(buf, offset, length);
 236           }
 237
 238         if (length > wavail)
 239           length = wavail;
 240         System.arraycopy(work, wpos, buf, offset, length);
 241         wpos += length;
 242         return length;
 243       }
 244   }
 245
 246   /**
 247    * This method reads a single character of data from the stream.
 248    *
 249    * @return The char read, as an int, or -1 if end of stream.
 250    *
 251    * @exception IOException If an error occurs
 252    */
 253   public int read() throws IOException
 254   {
 255     synchronized (lock)
 256       {
 257         if (in == null)
 258           throw new IOException("Stream closed");
 259
 260         int wavail = wcount - wpos;
 261         if (wavail <= 0)
 262           {
 263             // Nothing waiting, so refill our internal buffer.
 264             wpos = wcount = 0;
 265             if (work == null)
 266                work = new char[100];
 267             int count = refill(work, 0, work.length);
 268             if (count == -1)
 269               return -1;
 270             wcount += count;
 271           }
 272
 273         return work[wpos++];
 274       }
 275   }
 276
 277   // Read more bytes and convert them into the specified buffer.
 278   // Returns the number of converted characters or -1 on EOF.
 279   private int refill(char[] buf, int offset, int length) throws IOException
 280   {
 281     for (;;)
 282       {
 283         // We have knowledge of the internals of BufferedInputStream
 284         // here.  Eww.
 285         in.mark (0);
 286         // BufferedInputStream.refill() can only be called when
 287         // `pos>=count'.
 288         boolean r = in.pos < in.count || in.refill ();
 289         in.reset ();
 290         if (! r)
 291           return -1;
 292         converter.setInput(in.buf, in.pos, in.count);
 293         int count = converter.read(buf, offset, length);
 294         in.skip(converter.inpos - in.pos);
 295         if (count > 0)
 296           return count;
 297       }
 298   }
 299 }