1 /* 2 * Copyright (c) 1996, 2013, 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 charset}. 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 1.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 sd = StreamDecoder.forInputStreamReader(in, this, 74 Charset.defaultCharset()); // ## check lock object 75 } 76 77 /** 78 * Creates an InputStreamReader that uses the named charset. 79 * 80 * @param in 81 * An InputStream 82 * 83 * @param charsetName 84 * The name of a supported 85 * {@link java.nio.charset.Charset charset} 86 * 87 * @exception UnsupportedEncodingException 88 * If the named charset is not supported 89 */ InputStreamReader(InputStream in, String charsetName)90 public InputStreamReader(InputStream in, String charsetName) 91 throws UnsupportedEncodingException 92 { 93 super(in); 94 if (charsetName == null) 95 throw new NullPointerException("charsetName"); 96 sd = StreamDecoder.forInputStreamReader(in, this, charsetName); 97 } 98 99 /** 100 * Creates an InputStreamReader that uses the given charset. 101 * 102 * @param in An InputStream 103 * @param cs A charset 104 * 105 * @since 1.4 106 * @spec JSR-51 107 */ InputStreamReader(InputStream in, Charset cs)108 public InputStreamReader(InputStream in, Charset cs) { 109 super(in); 110 if (cs == null) 111 throw new NullPointerException("charset"); 112 sd = StreamDecoder.forInputStreamReader(in, this, cs); 113 } 114 115 /** 116 * Creates an InputStreamReader that uses the given charset decoder. 117 * 118 * @param in An InputStream 119 * @param dec A charset decoder 120 * 121 * @since 1.4 122 * @spec JSR-51 123 */ InputStreamReader(InputStream in, CharsetDecoder dec)124 public InputStreamReader(InputStream in, CharsetDecoder dec) { 125 super(in); 126 if (dec == null) 127 throw new NullPointerException("charset decoder"); 128 sd = StreamDecoder.forInputStreamReader(in, this, dec); 129 } 130 131 /** 132 * Returns the name of the character encoding being used by this stream. 133 * 134 * <p> If the encoding has an historical name then that name is returned; 135 * otherwise the encoding's canonical name is returned. 136 * 137 * <p> If this instance was created with the {@link 138 * #InputStreamReader(InputStream, String)} constructor then the returned 139 * name, being unique for the encoding, may differ from the name passed to 140 * the constructor. This method will return <code>null</code> if the 141 * stream has been closed. 142 * </p> 143 * @return The historical name of this encoding, or 144 * <code>null</code> if the stream has been closed 145 * 146 * @see java.nio.charset.Charset 147 * 148 * @revised 1.4 149 * @spec JSR-51 150 */ getEncoding()151 public String getEncoding() { 152 return sd.getEncoding(); 153 } 154 155 /** 156 * Reads a single character. 157 * 158 * @return The character read, or -1 if the end of the stream has been 159 * reached 160 * 161 * @exception IOException If an I/O error occurs 162 */ read()163 public int read() throws IOException { 164 return sd.read(); 165 } 166 167 /** 168 * Reads characters into a portion of an array. 169 * 170 * @param cbuf Destination buffer 171 * @param offset Offset at which to start storing characters 172 * @param length Maximum number of characters to read 173 * 174 * @return The number of characters read, or -1 if the end of the 175 * stream has been reached 176 * 177 * @exception IOException If an I/O error occurs 178 */ read(char cbuf[], int offset, int length)179 public int read(char cbuf[], int offset, int length) throws IOException { 180 return sd.read(cbuf, offset, length); 181 } 182 183 /** 184 * Tells whether this stream is ready to be read. An InputStreamReader is 185 * ready if its input buffer is not empty, or if bytes are available to be 186 * read from the underlying byte stream. 187 * 188 * @exception IOException If an I/O error occurs 189 */ ready()190 public boolean ready() throws IOException { 191 return sd.ready(); 192 } 193 close()194 public void close() throws IOException { 195 sd.close(); 196 } 197 } 198