1 /* 2 * Copyright (c) 1996, 2012, 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 29 /** 30 * Abstract class for reading character streams. The only methods that a 31 * subclass must implement are read(char[], int, int) and close(). Most 32 * subclasses, however, will override some of the methods defined here in order 33 * to provide higher efficiency, additional functionality, or both. 34 * 35 * 36 * @see BufferedReader 37 * @see LineNumberReader 38 * @see CharArrayReader 39 * @see InputStreamReader 40 * @see FileReader 41 * @see FilterReader 42 * @see PushbackReader 43 * @see PipedReader 44 * @see StringReader 45 * @see Writer 46 * 47 * @author Mark Reinhold 48 * @since 1.1 49 */ 50 51 public abstract class Reader implements Readable, Closeable { 52 53 /** 54 * The object used to synchronize operations on this stream. For 55 * efficiency, a character-stream object may use an object other than 56 * itself to protect critical sections. A subclass should therefore use 57 * the object in this field rather than <tt>this</tt> or a synchronized 58 * method. 59 */ 60 protected Object lock; 61 62 /** 63 * Creates a new character-stream reader whose critical sections will 64 * synchronize on the reader itself. 65 */ 66 protected Reader() { 67 this.lock = this; 68 } 69 70 /** 71 * Creates a new character-stream reader whose critical sections will 72 * synchronize on the given object. 73 * 74 * @param lock The Object to synchronize on. 75 */ 76 protected Reader(Object lock) { 77 if (lock == null) { 78 throw new NullPointerException(); 79 } 80 this.lock = lock; 81 } 82 83 /** 84 * Attempts to read characters into the specified character buffer. 85 * The buffer is used as a repository of characters as-is: the only 86 * changes made are the results of a put operation. No flipping or 87 * rewinding of the buffer is performed. 88 * 89 * @param target the buffer to read characters into 90 * @return The number of characters added to the buffer, or 91 * -1 if this source of characters is at its end 92 * @throws IOException if an I/O error occurs 93 * @throws NullPointerException if target is null 94 * @throws java.nio.ReadOnlyBufferException if target is a read only buffer 95 * @since 1.5 96 */ 97 public int read(java.nio.CharBuffer target) throws IOException { 98 int len = target.remaining(); 99 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 * @exception IndexOutOfBoundsException 157 * If {@code off} is negative, or {@code len} is negative, 158 * or {@code off+len} is negative or greater than the length 159 * of the given array 160 */ 161 abstract public int read(char cbuf[], int off, int len) throws IOException; 162 163 /** Maximum skip-buffer size */ 164 private static final int maxSkipBufferSize = 8192; 165 166 /** Skip buffer, null until allocated */ 167 private char skipBuffer[] = null; 168 169 /** 170 * Skips characters. This method will block until some characters are 171 * available, an I/O error occurs, or the end of the stream is reached. 172 * 173 * @param n The number of characters to skip 174 * 175 * @return The number of characters actually skipped 176 * 177 * @exception IllegalArgumentException If <code>n</code> is negative. 178 * @exception IOException If an I/O error occurs 179 */ 180 public long skip(long n) throws IOException { 181 if (n < 0L) 182 throw new IllegalArgumentException("skip value is negative"); 183 int nn = (int) Math.min(n, maxSkipBufferSize); 184 synchronized (lock) { 185 if ((skipBuffer == null) || (skipBuffer.length < nn)) 186 skipBuffer = new char[nn]; 187 long r = n; 188 while (r > 0) { 189 int nc = read(skipBuffer, 0, (int)Math.min(r, nn)); 190 if (nc == -1) 191 break; 192 r -= nc; 193 } 194 return n - r; 195 } 196 } 197 198 /** 199 * Tells whether this stream is ready to be read. 200 * 201 * @return True if the next read() is guaranteed not to block for input, 202 * false otherwise. Note that returning false does not guarantee that the 203 * next read will block. 204 * 205 * @exception IOException If an I/O error occurs 206 */ 207 public boolean ready() throws IOException { 208 return false; 209 } 210 211 /** 212 * Tells whether this stream supports the mark() operation. The default 213 * implementation always returns false. Subclasses should override this 214 * method. 215 * 216 * @return true if and only if this stream supports the mark operation. 217 */ 218 public boolean markSupported() { 219 return false; 220 } 221 222 /** 223 * Marks the present position in the stream. Subsequent calls to reset() 224 * will attempt to reposition the stream to this point. Not all 225 * character-input streams support the mark() operation. 226 * 227 * @param readAheadLimit Limit on the number of characters that may be 228 * read while still preserving the mark. After 229 * reading this many characters, attempting to 230 * reset the stream may fail. 231 * 232 * @exception IOException If the stream does not support mark(), 233 * or if some other I/O error occurs 234 */ 235 public void mark(int readAheadLimit) throws IOException { 236 throw new IOException("mark() not supported"); 237 } 238 239 /** 240 * Resets the stream. If the stream has been marked, then attempt to 241 * reposition it at the mark. If the stream has not been marked, then 242 * attempt to reset it in some way appropriate to the particular stream, 243 * for example by repositioning it to its starting point. Not all 244 * character-input streams support the reset() operation, and some support 245 * reset() without supporting mark(). 246 * 247 * @exception IOException If the stream has not been marked, 248 * or if the mark has been invalidated, 249 * or if the stream does not support reset(), 250 * or if some other I/O error occurs 251 */ 252 public void reset() throws IOException { 253 throw new IOException("reset() not supported"); 254 } 255 256 /** 257 * Closes the stream and releases any system resources associated with 258 * it. Once the stream has been closed, further read(), ready(), 259 * mark(), reset(), or skip() invocations will throw an IOException. 260 * Closing a previously closed stream has no effect. 261 * 262 * @exception IOException If an I/O error occurs 263 */ 264 abstract public void close() throws IOException; 265 266 }