Home » openjdk-7 » java » io » [javadoc | source]

    1   /*
    2    * Copyright (c) 1996, 2005, Oracle and/or its affiliates. All rights reserved.
    3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
    4    *
    5    * This code is free software; you can redistribute it and/or modify it
    6    * under the terms of the GNU General Public License version 2 only, as
    7    * published by the Free Software Foundation.  Oracle designates this
    8    * particular file as subject to the "Classpath" exception as provided
    9    * by Oracle in the LICENSE file that accompanied this code.
   10    *
   11    * This code is distributed in the hope that it will be useful, but WITHOUT
   12    * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
   13    * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
   14    * version 2 for more details (a copy is included in the LICENSE file that
   15    * accompanied this code).
   16    *
   17    * You should have received a copy of the GNU General Public License version
   18    * 2 along with this work; if not, write to the Free Software Foundation,
   19    * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
   20    *
   21    * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
   22    * or visit www.oracle.com if you need additional information or have any
   23    * questions.
   24    */
   25   
   26   package java.io;
   27   
   28   import java.nio.charset.Charset;
   29   import java.nio.charset.CharsetDecoder;
   30   import sun.nio.cs.StreamDecoder;
   31   
   32   
   33   /**
   34    * An InputStreamReader is a bridge from byte streams to character streams: It
   35    * reads bytes and decodes them into characters using a specified {@link
   36    * java.nio.charset.Charset <code>charset</code>}.  The charset that it uses
   37    * may be specified by name or may be given explicitly, or the platform's
   38    * default charset may be accepted.
   39    *
   40    * <p> Each invocation of one of an InputStreamReader's read() methods may
   41    * cause one or more bytes to be read from the underlying byte-input stream.
   42    * To enable the efficient conversion of bytes to characters, more bytes may
   43    * be read ahead from the underlying stream than are necessary to satisfy the
   44    * current read operation.
   45    *
   46    * <p> For top efficiency, consider wrapping an InputStreamReader within a
   47    * BufferedReader.  For example:
   48    *
   49    * <pre>
   50    * BufferedReader in
   51    *   = new BufferedReader(new InputStreamReader(System.in));
   52    * </pre>
   53    *
   54    * @see BufferedReader
   55    * @see InputStream
   56    * @see java.nio.charset.Charset
   57    *
   58    * @author      Mark Reinhold
   59    * @since       JDK1.1
   60    */
   61   
   62   public class InputStreamReader extends Reader {
   63   
   64       private final StreamDecoder sd;
   65   
   66       /**
   67        * Creates an InputStreamReader that uses the default charset.
   68        *
   69        * @param  in   An InputStream
   70        */
   71       public InputStreamReader(InputStream in) {
   72           super(in);
   73           try {
   74               sd = StreamDecoder.forInputStreamReader(in, this, (String)null); // ## check lock object
   75           } catch (UnsupportedEncodingException e) {
   76               // The default encoding should always be available
   77               throw new Error(e);
   78           }
   79       }
   80   
   81       /**
   82        * Creates an InputStreamReader that uses the named charset.
   83        *
   84        * @param  in
   85        *         An InputStream
   86        *
   87        * @param  charsetName
   88        *         The name of a supported
   89        *         {@link java.nio.charset.Charset </code>charset<code>}
   90        *
   91        * @exception  UnsupportedEncodingException
   92        *             If the named charset is not supported
   93        */
   94       public InputStreamReader(InputStream in, String charsetName)
   95           throws UnsupportedEncodingException
   96       {
   97           super(in);
   98           if (charsetName == null)
   99               throw new NullPointerException("charsetName");
  100           sd = StreamDecoder.forInputStreamReader(in, this, charsetName);
  101       }
  102   
  103       /**
  104        * Creates an InputStreamReader that uses the given charset. </p>
  105        *
  106        * @param  in       An InputStream
  107        * @param  cs       A charset
  108        *
  109        * @since 1.4
  110        * @spec JSR-51
  111        */
  112       public InputStreamReader(InputStream in, Charset cs) {
  113           super(in);
  114           if (cs == null)
  115               throw new NullPointerException("charset");
  116           sd = StreamDecoder.forInputStreamReader(in, this, cs);
  117       }
  118   
  119       /**
  120        * Creates an InputStreamReader that uses the given charset decoder.  </p>
  121        *
  122        * @param  in       An InputStream
  123        * @param  dec      A charset decoder
  124        *
  125        * @since 1.4
  126        * @spec JSR-51
  127        */
  128       public InputStreamReader(InputStream in, CharsetDecoder dec) {
  129           super(in);
  130           if (dec == null)
  131               throw new NullPointerException("charset decoder");
  132           sd = StreamDecoder.forInputStreamReader(in, this, dec);
  133       }
  134   
  135       /**
  136        * Returns the name of the character encoding being used by this stream.
  137        *
  138        * <p> If the encoding has an historical name then that name is returned;
  139        * otherwise the encoding's canonical name is returned.
  140        *
  141        * <p> If this instance was created with the {@link
  142        * #InputStreamReader(InputStream, String)} constructor then the returned
  143        * name, being unique for the encoding, may differ from the name passed to
  144        * the constructor. This method will return <code>null</code> if the
  145        * stream has been closed.
  146        * </p>
  147        * @return The historical name of this encoding, or
  148        *         <code>null</code> if the stream has been closed
  149        *
  150        * @see java.nio.charset.Charset
  151        *
  152        * @revised 1.4
  153        * @spec JSR-51
  154        */
  155       public String getEncoding() {
  156           return sd.getEncoding();
  157       }
  158   
  159       /**
  160        * Reads a single character.
  161        *
  162        * @return The character read, or -1 if the end of the stream has been
  163        *         reached
  164        *
  165        * @exception  IOException  If an I/O error occurs
  166        */
  167       public int read() throws IOException {
  168           return sd.read();
  169       }
  170   
  171       /**
  172        * Reads characters into a portion of an array.
  173        *
  174        * @param      cbuf     Destination buffer
  175        * @param      offset   Offset at which to start storing characters
  176        * @param      length   Maximum number of characters to read
  177        *
  178        * @return     The number of characters read, or -1 if the end of the
  179        *             stream has been reached
  180        *
  181        * @exception  IOException  If an I/O error occurs
  182        */
  183       public int read(char cbuf[], int offset, int length) throws IOException {
  184           return sd.read(cbuf, offset, length);
  185       }
  186   
  187       /**
  188        * Tells whether this stream is ready to be read.  An InputStreamReader is
  189        * ready if its input buffer is not empty, or if bytes are available to be
  190        * read from the underlying byte stream.
  191        *
  192        * @exception  IOException  If an I/O error occurs
  193        */
  194       public boolean ready() throws IOException {
  195           return sd.ready();
  196       }
  197   
  198       public void close() throws IOException {
  199           sd.close();
  200       }
  201   }

Home » openjdk-7 » java » io » [javadoc | source]