1 /*
2  * Copyright (c) 1996, 2021, 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.CharBuffer;
29 import java.nio.charset.Charset;
30 import java.nio.charset.CharsetDecoder;
31 import sun.nio.cs.StreamDecoder;
32 
33 
34 /**
35  * An InputStreamReader is a bridge from byte streams to character streams: It
36  * reads bytes and decodes them into characters using a specified {@link
37  * java.nio.charset.Charset charset}.  The charset that it uses
38  * may be specified by name or may be given explicitly, or the platform's
39  * {@link Charset#defaultCharset() default charset} may be accepted.
40  *
41  * <p> Each invocation of one of an InputStreamReader's read() methods may
42  * cause one or more bytes to be read from the underlying byte-input stream.
43  * To enable the efficient conversion of bytes to characters, more bytes may
44  * be read ahead from the underlying stream than are necessary to satisfy the
45  * current read operation.
46  *
47  * <p> For top efficiency, consider wrapping an InputStreamReader within a
48  * BufferedReader.  For example:
49  *
50  * <pre>
51  * BufferedReader in
52  *   = new BufferedReader(new InputStreamReader(anInputStream));
53  * </pre>
54  *
55  * @see BufferedReader
56  * @see InputStream
57  * @see java.nio.charset.Charset
58  *
59  * @author      Mark Reinhold
60  * @since       1.1
61  */
62 
63 public class InputStreamReader extends Reader {
64 
65     private final StreamDecoder sd;
66 
67     /**
68      * Creates an InputStreamReader that uses the
69      * {@link Charset#defaultCharset() default charset}.
70      *
71      * @param  in   An InputStream
72      *
73      * @see Charset#defaultCharset()
74      */
InputStreamReader(InputStream in)75     public InputStreamReader(InputStream in) {
76         super(in);
77         sd = StreamDecoder.forInputStreamReader(in, this,
78                 Charset.defaultCharset()); // ## check lock object
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 charset}
90      *
91      * @throws     UnsupportedEncodingException
92      *             If the named charset is not supported
93      */
InputStreamReader(InputStream in, String charsetName)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.
105      *
106      * @param  in       An InputStream
107      * @param  cs       A charset
108      *
109      * @since 1.4
110      */
InputStreamReader(InputStream in, Charset cs)111     public InputStreamReader(InputStream in, Charset cs) {
112         super(in);
113         if (cs == null)
114             throw new NullPointerException("charset");
115         sd = StreamDecoder.forInputStreamReader(in, this, cs);
116     }
117 
118     /**
119      * Creates an InputStreamReader that uses the given charset decoder.
120      *
121      * @param  in       An InputStream
122      * @param  dec      A charset decoder
123      *
124      * @since 1.4
125      */
InputStreamReader(InputStream in, CharsetDecoder dec)126     public InputStreamReader(InputStream in, CharsetDecoder dec) {
127         super(in);
128         if (dec == null)
129             throw new NullPointerException("charset decoder");
130         sd = StreamDecoder.forInputStreamReader(in, this, dec);
131     }
132 
133     /**
134      * Returns the name of the character encoding being used by this stream.
135      *
136      * <p> If the encoding has an historical name then that name is returned;
137      * otherwise the encoding's canonical name is returned.
138      *
139      * <p> If this instance was created with the {@link
140      * #InputStreamReader(InputStream, String)} constructor then the returned
141      * name, being unique for the encoding, may differ from the name passed to
142      * the constructor. This method will return {@code null} if the
143      * stream has been closed.
144      * </p>
145      * @return The historical name of this encoding, or
146      *         {@code null} if the stream has been closed
147      *
148      * @see java.nio.charset.Charset
149      *
150      * @revised 1.4
151      */
getEncoding()152     public String getEncoding() {
153         return sd.getEncoding();
154     }
155 
read(CharBuffer target)156     public int read(CharBuffer target) throws IOException {
157         return sd.read(target);
158     }
159 
160     /**
161      * Reads a single character.
162      *
163      * @return The character read, or -1 if the end of the stream has been
164      *         reached
165      *
166      * @throws     IOException  If an I/O error occurs
167      */
read()168     public int read() throws IOException {
169         return sd.read();
170     }
171 
172     /**
173      * {@inheritDoc}
174      * @throws     IndexOutOfBoundsException  {@inheritDoc}
175      */
read(char[] cbuf, int off, int len)176     public int read(char[] cbuf, int off, int len) throws IOException {
177         return sd.read(cbuf, off, len);
178     }
179 
180     /**
181      * Tells whether this stream is ready to be read.  An InputStreamReader is
182      * ready if its input buffer is not empty, or if bytes are available to be
183      * read from the underlying byte stream.
184      *
185      * @throws     IOException  If an I/O error occurs
186      */
ready()187     public boolean ready() throws IOException {
188         return sd.ready();
189     }
190 
close()191     public void close() throws IOException {
192         sd.close();
193     }
194 }
195