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 26package 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 51public 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 {@code this} 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 * ({@code 0x00-0xffff}), 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 len} is greater than {@code cbuf.length - off} 159 */ 160 public abstract int read(char cbuf[], int off, int len) throws IOException; 161 162 /** Maximum skip-buffer size */ 163 private static final int maxSkipBufferSize = 8192; 164 165 /** Skip buffer, null until allocated */ 166 private char skipBuffer[] = null; 167 168 /** 169 * Skips characters. This method will block until some characters are 170 * available, an I/O error occurs, or the end of the stream is reached. 171 * 172 * @param n The number of characters to skip 173 * 174 * @return The number of characters actually skipped 175 * 176 * @exception IllegalArgumentException If <code>n</code> is negative. 177 * @exception IOException If an I/O error occurs 178 */ 179 public long skip(long n) throws IOException { 180 if (n < 0L) 181 throw new IllegalArgumentException("skip value is negative"); 182 int nn = (int) Math.min(n, maxSkipBufferSize); 183 synchronized (lock) { 184 if ((skipBuffer == null) || (skipBuffer.length < nn)) 185 skipBuffer = new char[nn]; 186 long r = n; 187 while (r > 0) { 188 int nc = read(skipBuffer, 0, (int)Math.min(r, nn)); 189 if (nc == -1) 190 break; 191 r -= nc; 192 } 193 return n - r; 194 } 195 } 196 197 /** 198 * Tells whether this stream is ready to be read. 199 * 200 * @return True if the next read() is guaranteed not to block for input, 201 * false otherwise. Note that returning false does not guarantee that the 202 * next read will block. 203 * 204 * @exception IOException If an I/O error occurs 205 */ 206 public boolean ready() throws IOException { 207 return false; 208 } 209 210 /** 211 * Tells whether this stream supports the mark() operation. The default 212 * implementation always returns false. Subclasses should override this 213 * method. 214 * 215 * @return true if and only if this stream supports the mark operation. 216 */ 217 public boolean markSupported() { 218 return false; 219 } 220 221 /** 222 * Marks the present position in the stream. Subsequent calls to reset() 223 * will attempt to reposition the stream to this point. Not all 224 * character-input streams support the mark() operation. 225 * 226 * @param readAheadLimit Limit on the number of characters that may be 227 * read while still preserving the mark. After 228 * reading this many characters, attempting to 229 * reset the stream may fail. 230 * 231 * @exception IOException If the stream does not support mark(), 232 * or if some other I/O error occurs 233 */ 234 public void mark(int readAheadLimit) throws IOException { 235 throw new IOException("mark() not supported"); 236 } 237 238 /** 239 * Resets the stream. If the stream has been marked, then attempt to 240 * reposition it at the mark. If the stream has not been marked, then 241 * attempt to reset it in some way appropriate to the particular stream, 242 * for example by repositioning it to its starting point. Not all 243 * character-input streams support the reset() operation, and some support 244 * reset() without supporting mark(). 245 * 246 * @exception IOException If the stream has not been marked, 247 * or if the mark has been invalidated, 248 * or if the stream does not support reset(), 249 * or if some other I/O error occurs 250 */ 251 public void reset() throws IOException { 252 throw new IOException("reset() not supported"); 253 } 254 255 /** 256 * Closes the stream and releases any system resources associated with 257 * it. Once the stream has been closed, further read(), ready(), 258 * mark(), reset(), or skip() invocations will throw an IOException. 259 * Closing a previously closed stream has no effect. 260 * 261 * @exception IOException If an I/O error occurs 262 */ 263 public abstract void close() throws IOException; 264 265} 266