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 */ InputStreamReader(InputStream in)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 */ 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. </p> 105 * 106 * @param in An InputStream 107 * @param cs A charset 108 * 109 * @since 1.4 110 * @spec JSR-51 111 */ InputStreamReader(InputStream in, Charset cs)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 */ InputStreamReader(InputStream in, CharsetDecoder dec)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 */ getEncoding()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 */ read()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 */ read(char cbuf[], int offset, int length)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 */ ready()194 public boolean ready() throws IOException { 195 return sd.ready(); 196 } 197 close()198 public void close() throws IOException { 199 sd.close(); 200 } 201 } 202