KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > io > InputStreamReader


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
8 package java.io;
9
10 import java.nio.charset.Charset JavaDoc;
11 import java.nio.charset.CharsetDecoder JavaDoc;
12 import sun.nio.cs.StreamDecoder;
13
14
15 /**
16  * An InputStreamReader is a bridge from byte streams to character streams: It
17  * reads bytes and decodes them into characters using a specified {@link
18  * java.nio.charset.Charset <code>charset</code>}. The charset that it uses
19  * may be specified by name or may be given explicitly, or the platform's
20  * default charset may be accepted.
21  *
22  * <p> Each invocation of one of an InputStreamReader's read() methods may
23  * cause one or more bytes to be read from the underlying byte-input stream.
24  * To enable the efficient conversion of bytes to characters, more bytes may
25  * be read ahead from the underlying stream than are necessary to satisfy the
26  * current read operation.
27  *
28  * <p> For top efficiency, consider wrapping an InputStreamReader within a
29  * BufferedReader. For example:
30  *
31  * <pre>
32  * BufferedReader in
33  * = new BufferedReader(new InputStreamReader(System.in));
34  * </pre>
35  *
36  * @see BufferedReader
37  * @see InputStream
38  * @see java.nio.charset.Charset
39  *
40  * @version 1.44, 03/12/19
41  * @author Mark Reinhold
42  * @since JDK1.1
43  */
44
45 public class InputStreamReader extends Reader JavaDoc {
46
47     private final StreamDecoder sd;
48
49     /**
50      * Create an InputStreamReader that uses the default charset.
51      *
52      * @param in An InputStream
53      */
54     public InputStreamReader(InputStream JavaDoc in) {
55     super(in);
56         try {
57         sd = StreamDecoder.forInputStreamReader(in, this, (String JavaDoc)null); // ## check lock object
58 } catch (UnsupportedEncodingException JavaDoc e) {
59         // The default encoding should always be available
60 throw new Error JavaDoc(e);
61     }
62     }
63
64     /**
65      * Create an InputStreamReader that uses the named charset.
66      *
67      * @param in
68      * An InputStream
69      *
70      * @param charsetName
71      * The name of a supported
72      * {@link java.nio.charset.Charset </code>charset<code>}
73      *
74      * @exception UnsupportedEncodingException
75      * If the named charset is not supported
76      */
77     public InputStreamReader(InputStream JavaDoc in, String JavaDoc charsetName)
78         throws UnsupportedEncodingException JavaDoc
79     {
80     super(in);
81     if (charsetName == null)
82         throw new NullPointerException JavaDoc("charsetName");
83     sd = StreamDecoder.forInputStreamReader(in, this, charsetName);
84     }
85
86     /**
87      * Create an InputStreamReader that uses the given charset. </p>
88      *
89      * @param in An InputStream
90      * @param cs A charset
91      *
92      * @since 1.4
93      * @spec JSR-51
94      */
95     public InputStreamReader(InputStream JavaDoc in, Charset JavaDoc cs) {
96         super(in);
97     if (cs == null)
98         throw new NullPointerException JavaDoc("charset");
99     sd = StreamDecoder.forInputStreamReader(in, this, cs);
100     }
101
102     /**
103      * Create 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 JavaDoc in, CharsetDecoder JavaDoc dec) {
112         super(in);
113     if (dec == null)
114         throw new NullPointerException JavaDoc("charset decoder");
115     sd = StreamDecoder.forInputStreamReader(in, this, dec);
116     }
117
118     /**
119      * Return 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 may return <code>null</code> if the stream
128      * has been closed. </p>
129      *
130      * @return The historical name of this encoding, or possibly
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 JavaDoc getEncoding() {
139     return sd.getEncoding();
140     }
141
142     /**
143      * Read 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 JavaDoc {
151         return sd.read();
152     }
153
154     /**
155      * Read 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 JavaDoc {
167     return sd.read(cbuf, offset, length);
168     }
169
170     /**
171      * Tell 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 JavaDoc {
178     return sd.ready();
179     }
180
181     /**
182      * Close the stream.
183      *
184      * @exception IOException If an I/O error occurs
185      */
186     public void close() throws IOException JavaDoc {
187     sd.close();
188     }
189
190 }
191
Popular Tags