- 001
/* - 002
* @(#)InputStreamReader.java 1.47 05/11/17 - 003 *
- 004 * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
- 005 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
- 006
*/ - 007
- 008package java.io;
- 009
- 010import java.nio.charset.Charset;
- 011import java.nio.charset.CharsetDecoder;
- 012import sun.nio.cs.StreamDecoder;
- 013
- 014
- 015/**
- 016 * An InputStreamReader is a bridge from byte streams to character streams: It
- 017 * reads bytes and decodes them into characters using a specified {@link
- 018 * java.nio.charset.Charset <code>charset</code>}. The charset that it uses
- 019 * may be specified by name or may be given explicitly, or the platform's
- 020 * default charset may be accepted.
- 021 *
- 022 * <p> Each invocation of one of an InputStreamReader's read() methods may
- 023 * cause one or more bytes to be read from the underlying byte-input stream.
- 024 * To enable the efficient conversion of bytes to characters, more bytes may
- 025 * be read ahead from the underlying stream than are necessary to satisfy the
- 026 * current read operation.
- 027 *
- 028 * <p> For top efficiency, consider wrapping an InputStreamReader within a
- 029 * BufferedReader. For example:
- 030 *
- 031 * <pre>
- 032 * BufferedReader in
- 033 * = new BufferedReader(new InputStreamReader(System.in));
- 034 * </pre>
- 035 *
- 036 * @see BufferedReader
- 037 * @see InputStream
- 038 * @see java.nio.charset.Charset
- 039 *
- 040 * @version 1.47, 05/11/17
- 041 * @author Mark Reinhold
- 042 * @since JDK1.1
- 043 */
- 044
- 045public class InputStreamReader extends Reader {
- 046
- 047 private final StreamDecoder sd;
- 048
- 049 /**
- 050 * Creates an InputStreamReader that uses the default charset.
- 051 *
- 052 * @param in An InputStream
- 053 */
- 054 public InputStreamReader(InputStream in) {
- 055 super(in);
- 056 try {
- 057 sd = StreamDecoder.forInputStreamReader(in, this, (String)null); // ## check lock object
- 058 } catch (UnsupportedEncodingException e) {
- 059 // The default encoding should always be available
- 060 throw new Error(e);
- 061 }
- 062 }
- 063
- 064 /**
- 065 * Creates an InputStreamReader that uses the named charset.
- 066 *
- 067 * @param in
- 068 * An InputStream
- 069 *
- 070 * @param charsetName
- 071 * The name of a supported
- 072 * {@link java.nio.charset.Charset </code>charset<code>}
- 073 *
- 074 * @exception UnsupportedEncodingException
- 075 * If the named charset is not supported
- 076 */
- 077 public InputStreamReader(InputStream in, String charsetName)
- 078 throws UnsupportedEncodingException
- 079 {
- 080 super(in);
- 081 if (charsetName == null)
- 082 throw new NullPointerException("charsetName");
- 083 sd = StreamDecoder.forInputStreamReader(in, this, charsetName);
- 084 }
- 085
- 086 /**
- 087 * Creates an InputStreamReader that uses the given charset. </p>
- 088 *
- 089 * @param in An InputStream
- 090 * @param cs A charset
- 091 *
- 092 * @since 1.4
- 093 * @spec JSR-51
- 094 */
- 095 public InputStreamReader(InputStream in, Charset cs) {
- 096 super(in);
- 097 if (cs == null)
- 098 throw new NullPointerException("charset");
- 099 sd = StreamDecoder.forInputStreamReader(in, this, cs);
- 100 }
- 101
- 102 /**
- 103 * Creates an InputStreamReader that uses the given charset decoder. </p>
- 104 *
- 105 * @param in An InputStream
- 106 * @param dec A charset decoder
- 107 *
- 108 * @since 1.4
- 109 * @spec JSR-51
- 110 */
- 111 public InputStreamReader(InputStream in, CharsetDecoder dec) {
- 112 super(in);
- 113 if (dec == null)
- 114 throw new NullPointerException("charset decoder");
- 115 sd = StreamDecoder.forInputStreamReader(in, this, dec);
- 116 }
- 117
- 118 /**
- 119 * Returns the name of the character encoding being used by this stream.
- 120 *
- 121 * <p> If the encoding has an historical name then that name is returned;
- 122 * otherwise the encoding's canonical name is returned.
- 123 *
- 124 * <p> If this instance was created with the {@link
- 125 * #InputStreamReader(InputStream, String)} constructor then the returned
- 126 * name, being unique for the encoding, may differ from the name passed to
- 127 * the constructor. This method will return <code>null</code> if the
- 128 * stream has been closed.
- 129 * </p>
- 130 * @return The historical name of this encoding, or
- 131 * <code>null</code> if the stream has been closed
- 132 *
- 133 * @see java.nio.charset.Charset
- 134 *
- 135 * @revised 1.4
- 136 * @spec JSR-51
- 137 */
- 138 public String getEncoding() {
- 139 return sd.getEncoding();
- 140 }
- 141
- 142 /**
- 143 * Reads a single character.
- 144 *
- 145 * @return The character read, or -1 if the end of the stream has been
- 146 * reached
- 147 *
- 148 * @exception IOException If an I/O error occurs
- 149 */
- 150 public int read() throws IOException {
- 151 return sd.read();
- 152 }
- 153
- 154 /**
- 155 * Reads characters into a portion of an array.
- 156 *
- 157 * @param cbuf Destination buffer
- 158 * @param offset Offset at which to start storing characters
- 159 * @param length Maximum number of characters to read
- 160 *
- 161 * @return The number of characters read, or -1 if the end of the
- 162 * stream has been reached
- 163 *
- 164 * @exception IOException If an I/O error occurs
- 165 */
- 166 public int read(char cbuf[], int offset, int length) throws IOException {
- 167 return sd.read(cbuf, offset, length);
- 168 }
- 169
- 170 /**
- 171 * Tells whether this stream is ready to be read. An InputStreamReader is
- 172 * ready if its input buffer is not empty, or if bytes are available to be
- 173 * read from the underlying byte stream.
- 174 *
- 175 * @exception IOException If an I/O error occurs
- 176 */
- 177 public boolean ready() throws IOException {
- 178 return sd.ready();
- 179 }
- 180
- 181 public void close() throws IOException {
- 182 sd.close();
- 183 }
- 184}
