001 /*
002 * Copyright 1996-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.io;
027
028 /**
029 * Abstract class for reading character streams. The only methods that a
030 * subclass must implement are read(char[], int, int) and close(). Most
031 * subclasses, however, will override some of the methods defined here in order
032 * to provide higher efficiency, additional functionality, or both.
033 *
034 *
035 * @see BufferedReader
036 * @see LineNumberReader
037 * @see CharArrayReader
038 * @see InputStreamReader
039 * @see FileReader
040 * @see FilterReader
041 * @see PushbackReader
042 * @see PipedReader
043 * @see StringReader
044 * @see Writer
045 *
046 * @version 1.36, 07/05/05
047 * @author Mark Reinhold
048 * @since JDK1.1
049 */
050
051 public abstract class Reader implements Readable, Closeable {
052
053 /**
054 * The object used to synchronize operations on this stream. For
055 * efficiency, a character-stream object may use an object other than
056 * itself to protect critical sections. A subclass should therefore use
057 * the object in this field rather than <tt>this</tt> or a synchronized
058 * method.
059 */
060 protected Object lock;
061
062 /**
063 * Creates a new character-stream reader whose critical sections will
064 * synchronize on the reader itself.
065 */
066 protected Reader() {
067 this .lock = this ;
068 }
069
070 /**
071 * Creates a new character-stream reader whose critical sections will
072 * synchronize on the given object.
073 *
074 * @param lock The Object to synchronize on.
075 */
076 protected Reader(Object lock) {
077 if (lock == null) {
078 throw new NullPointerException();
079 }
080 this .lock = lock;
081 }
082
083 /**
084 * Attempts to read characters into the specified character buffer.
085 * The buffer is used as a repository of characters as-is: the only
086 * changes made are the results of a put operation. No flipping or
087 * rewinding of the buffer is performed.
088 *
089 * @param target the buffer to read characters into
090 * @return The number of characters added to the buffer, or
091 * -1 if this source of characters is at its end
092 * @throws IOException if an I/O error occurs
093 * @throws NullPointerException if target is null
094 * @throws ReadOnlyBufferException if target is a read only buffer
095 * @since 1.5
096 */
097 public int read(java.nio.CharBuffer target) throws IOException {
098 int len = target.remaining();
099 char[] cbuf = new char[len];
100 int n = read(cbuf, 0, len);
101 if (n > 0)
102 target.put(cbuf, 0, n);
103 return n;
104 }
105
106 /**
107 * Reads a single character. This method will block until a character is
108 * available, an I/O error occurs, or the end of the stream is reached.
109 *
110 * <p> Subclasses that intend to support efficient single-character input
111 * should override this method.
112 *
113 * @return The character read, as an integer in the range 0 to 65535
114 * (<tt>0x00-0xffff</tt>), or -1 if the end of the stream has
115 * been reached
116 *
117 * @exception IOException If an I/O error occurs
118 */
119 public int read() throws IOException {
120 char cb[] = new char[1];
121 if (read(cb, 0, 1) == -1)
122 return -1;
123 else
124 return cb[0];
125 }
126
127 /**
128 * Reads characters into an array. This method will block until some input
129 * is available, an I/O error occurs, or the end of the stream is reached.
130 *
131 * @param cbuf Destination buffer
132 *
133 * @return The number of characters read, or -1
134 * if the end of the stream
135 * has been reached
136 *
137 * @exception IOException If an I/O error occurs
138 */
139 public int read(char cbuf[]) throws IOException {
140 return read(cbuf, 0, cbuf.length);
141 }
142
143 /**
144 * Reads characters into a portion of an array. This method will block
145 * until some input is available, an I/O error occurs, or the end of the
146 * stream is reached.
147 *
148 * @param cbuf Destination buffer
149 * @param off Offset at which to start storing characters
150 * @param len Maximum number of characters to read
151 *
152 * @return The number of characters read, or -1 if the end of the
153 * stream has been reached
154 *
155 * @exception IOException If an I/O error occurs
156 */
157 abstract public int read(char cbuf[], int off, int len)
158 throws IOException;
159
160 /** Maximum skip-buffer size */
161 private static final int maxSkipBufferSize = 8192;
162
163 /** Skip buffer, null until allocated */
164 private char skipBuffer[] = null;
165
166 /**
167 * Skips characters. This method will block until some characters are
168 * available, an I/O error occurs, or the end of the stream is reached.
169 *
170 * @param n The number of characters to skip
171 *
172 * @return The number of characters actually skipped
173 *
174 * @exception IllegalArgumentException If <code>n</code> is negative.
175 * @exception IOException If an I/O error occurs
176 */
177 public long skip(long n) throws IOException {
178 if (n < 0L)
179 throw new IllegalArgumentException("skip value is negative");
180 int nn = (int) Math.min(n, maxSkipBufferSize);
181 synchronized (lock) {
182 if ((skipBuffer == null) || (skipBuffer.length < nn))
183 skipBuffer = new char[nn];
184 long r = n;
185 while (r > 0) {
186 int nc = read(skipBuffer, 0, (int) Math.min(r, nn));
187 if (nc == -1)
188 break;
189 r -= nc;
190 }
191 return n - r;
192 }
193 }
194
195 /**
196 * Tells whether this stream is ready to be read.
197 *
198 * @return True if the next read() is guaranteed not to block for input,
199 * false otherwise. Note that returning false does not guarantee that the
200 * next read will block.
201 *
202 * @exception IOException If an I/O error occurs
203 */
204 public boolean ready() throws IOException {
205 return false;
206 }
207
208 /**
209 * Tells whether this stream supports the mark() operation. The default
210 * implementation always returns false. Subclasses should override this
211 * method.
212 *
213 * @return true if and only if this stream supports the mark operation.
214 */
215 public boolean markSupported() {
216 return false;
217 }
218
219 /**
220 * Marks the present position in the stream. Subsequent calls to reset()
221 * will attempt to reposition the stream to this point. Not all
222 * character-input streams support the mark() operation.
223 *
224 * @param readAheadLimit Limit on the number of characters that may be
225 * read while still preserving the mark. After
226 * reading this many characters, attempting to
227 * reset the stream may fail.
228 *
229 * @exception IOException If the stream does not support mark(),
230 * or if some other I/O error occurs
231 */
232 public void mark(int readAheadLimit) throws IOException {
233 throw new IOException("mark() not supported");
234 }
235
236 /**
237 * Resets the stream. If the stream has been marked, then attempt to
238 * reposition it at the mark. If the stream has not been marked, then
239 * attempt to reset it in some way appropriate to the particular stream,
240 * for example by repositioning it to its starting point. Not all
241 * character-input streams support the reset() operation, and some support
242 * reset() without supporting mark().
243 *
244 * @exception IOException If the stream has not been marked,
245 * or if the mark has been invalidated,
246 * or if the stream does not support reset(),
247 * or if some other I/O error occurs
248 */
249 public void reset() throws IOException {
250 throw new IOException("reset() not supported");
251 }
252
253 /**
254 * Closes the stream and releases any system resources associated with
255 * it. Once the stream has been closed, further read(), ready(),
256 * mark(), reset(), or skip() invocations will throw an IOException.
257 * Closing a previously closed stream has no effect.
258 *
259 * @exception IOException If an I/O error occurs
260 */
261 abstract public void close() throws IOException;
262
263 }
|