1. /*
  2. * @(#)InputStreamReader.java 1.44 03/12/19
  3. *
  4. * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package java.io;
  8. import java.nio.charset.Charset;
  9. import java.nio.charset.CharsetDecoder;
  10. import sun.nio.cs.StreamDecoder;
  11. /**
  12. * An InputStreamReader is a bridge from byte streams to character streams: It
  13. * reads bytes and decodes them into characters using a specified {@link
  14. * java.nio.charset.Charset <code>charset</code>}. The charset that it uses
  15. * may be specified by name or may be given explicitly, or the platform's
  16. * default charset may be accepted.
  17. *
  18. * <p> Each invocation of one of an InputStreamReader's read() methods may
  19. * cause one or more bytes to be read from the underlying byte-input stream.
  20. * To enable the efficient conversion of bytes to characters, more bytes may
  21. * be read ahead from the underlying stream than are necessary to satisfy the
  22. * current read operation.
  23. *
  24. * <p> For top efficiency, consider wrapping an InputStreamReader within a
  25. * BufferedReader. For example:
  26. *
  27. * <pre>
  28. * BufferedReader in
  29. * = new BufferedReader(new InputStreamReader(System.in));
  30. * </pre>
  31. *
  32. * @see BufferedReader
  33. * @see InputStream
  34. * @see java.nio.charset.Charset
  35. *
  36. * @version 1.44, 03/12/19
  37. * @author Mark Reinhold
  38. * @since JDK1.1
  39. */
  40. public class InputStreamReader extends Reader {
  41. private final StreamDecoder sd;
  42. /**
  43. * Create an InputStreamReader that uses the default charset.
  44. *
  45. * @param in An InputStream
  46. */
  47. public InputStreamReader(InputStream in) {
  48. super(in);
  49. try {
  50. sd = StreamDecoder.forInputStreamReader(in, this, (String)null); // ## check lock object
  51. } catch (UnsupportedEncodingException e) {
  52. // The default encoding should always be available
  53. throw new Error(e);
  54. }
  55. }
  56. /**
  57. * Create an InputStreamReader that uses the named charset.
  58. *
  59. * @param in
  60. * An InputStream
  61. *
  62. * @param charsetName
  63. * The name of a supported
  64. * {@link java.nio.charset.Charset </code>charset<code>}
  65. *
  66. * @exception UnsupportedEncodingException
  67. * If the named charset is not supported
  68. */
  69. public InputStreamReader(InputStream in, String charsetName)
  70. throws UnsupportedEncodingException
  71. {
  72. super(in);
  73. if (charsetName == null)
  74. throw new NullPointerException("charsetName");
  75. sd = StreamDecoder.forInputStreamReader(in, this, charsetName);
  76. }
  77. /**
  78. * Create an InputStreamReader that uses the given charset. </p>
  79. *
  80. * @param in An InputStream
  81. * @param cs A charset
  82. *
  83. * @since 1.4
  84. * @spec JSR-51
  85. */
  86. public InputStreamReader(InputStream in, Charset cs) {
  87. super(in);
  88. if (cs == null)
  89. throw new NullPointerException("charset");
  90. sd = StreamDecoder.forInputStreamReader(in, this, cs);
  91. }
  92. /**
  93. * Create an InputStreamReader that uses the given charset decoder. </p>
  94. *
  95. * @param in An InputStream
  96. * @param dec A charset decoder
  97. *
  98. * @since 1.4
  99. * @spec JSR-51
  100. */
  101. public InputStreamReader(InputStream in, CharsetDecoder dec) {
  102. super(in);
  103. if (dec == null)
  104. throw new NullPointerException("charset decoder");
  105. sd = StreamDecoder.forInputStreamReader(in, this, dec);
  106. }
  107. /**
  108. * Return the name of the character encoding being used by this stream.
  109. *
  110. * <p> If the encoding has an historical name then that name is returned;
  111. * otherwise the encoding's canonical name is returned.
  112. *
  113. * <p> If this instance was created with the {@link
  114. * #InputStreamReader(InputStream, String)} constructor then the returned
  115. * name, being unique for the encoding, may differ from the name passed to
  116. * the constructor. This method may return <code>null</code> if the stream
  117. * has been closed. </p>
  118. *
  119. * @return The historical name of this encoding, or possibly
  120. * <code>null</code> if the stream has been closed
  121. *
  122. * @see java.nio.charset.Charset
  123. *
  124. * @revised 1.4
  125. * @spec JSR-51
  126. */
  127. public String getEncoding() {
  128. return sd.getEncoding();
  129. }
  130. /**
  131. * Read a single character.
  132. *
  133. * @return The character read, or -1 if the end of the stream has been
  134. * reached
  135. *
  136. * @exception IOException If an I/O error occurs
  137. */
  138. public int read() throws IOException {
  139. return sd.read();
  140. }
  141. /**
  142. * Read characters into a portion of an array.
  143. *
  144. * @param cbuf Destination buffer
  145. * @param offset Offset at which to start storing characters
  146. * @param length Maximum number of characters to read
  147. *
  148. * @return The number of characters read, or -1 if the end of the
  149. * stream has been reached
  150. *
  151. * @exception IOException If an I/O error occurs
  152. */
  153. public int read(char cbuf[], int offset, int length) throws IOException {
  154. return sd.read(cbuf, offset, length);
  155. }
  156. /**
  157. * Tell whether this stream is ready to be read. An InputStreamReader is
  158. * ready if its input buffer is not empty, or if bytes are available to be
  159. * read from the underlying byte stream.
  160. *
  161. * @exception IOException If an I/O error occurs
  162. */
  163. public boolean ready() throws IOException {
  164. return sd.ready();
  165. }
  166. /**
  167. * Close the stream.
  168. *
  169. * @exception IOException If an I/O error occurs
  170. */
  171. public void close() throws IOException {
  172. sd.close();
  173. }
  174. }