- 001
/* - 002
* @(#)InputStream.java 1.52 06/06/07 - 003 *
- 004 * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
- 005 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
- 006
*/ - 007
- 008package java.io;
- 009
- 010/**
- 011 * This abstract class is the superclass of all classes representing
- 012 * an input stream of bytes.
- 013 *
- 014 * <p> Applications that need to define a subclass of <code>InputStream</code>
- 015 * must always provide a method that returns the next byte of input.
- 016 *
- 017 * @author Arthur van Hoff
- 018 * @version 1.52, 06/07/06
- 019 * @see java.io.BufferedInputStream
- 020 * @see java.io.ByteArrayInputStream
- 021 * @see java.io.DataInputStream
- 022 * @see java.io.FilterInputStream
- 023 * @see java.io.InputStream#read()
- 024 * @see java.io.OutputStream
- 025 * @see java.io.PushbackInputStream
- 026 * @since JDK1.0
- 027 */
- 028public abstract class InputStream implements Closeable {
- 029
- 030 // SKIP_BUFFER_SIZE is used to determine the size of skipBuffer
- 031 private static final int SKIP_BUFFER_SIZE = 2048;
- 032 // skipBuffer is initialized in skip(long), if needed.
- 033 private static byte[] skipBuffer;
- 034
- 035 /**
- 036 * Reads the next byte of data from the input stream. The value byte is
- 037 * returned as an <code>int</code> in the range <code>0</code> to
- 038 * <code>255</code>. If no byte is available because the end of the stream
- 039 * has been reached, the value <code>-1</code> is returned. This method
- 040 * blocks until input data is available, the end of the stream is detected,
- 041 * or an exception is thrown.
- 042 *
- 043 * <p> A subclass must provide an implementation of this method.
- 044 *
- 045 * @return the next byte of data, or <code>-1</code> if the end of the
- 046 * stream is reached.
- 047 * @exception IOException if an I/O error occurs.
- 048 */
- 049 public abstract int read() throws IOException;
- 050
- 051 /**
- 052 * Reads some number of bytes from the input stream and stores them into
- 053 * the buffer array <code>b</code>. The number of bytes actually read is
- 054 * returned as an integer. This method blocks until input data is
- 055 * available, end of file is detected, or an exception is thrown.
- 056 *
- 057 * <p> If the length of <code>b</code> is zero, then no bytes are read and
- 058 * <code>0</code> is returned; otherwise, there is an attempt to read at
- 059 * least one byte. If no byte is available because the stream is at the
- 060 * end of the file, the value <code>-1</code> is returned; otherwise, at
- 061 * least one byte is read and stored into <code>b</code>.
- 062 *
- 063 * <p> The first byte read is stored into element <code>b[0]</code>, the
- 064 * next one into <code>b[1]</code>, and so on. The number of bytes read is,
- 065 * at most, equal to the length of <code>b</code>. Let <i>k</i> be the
- 066 * number of bytes actually read; these bytes will be stored in elements
- 067 * <code>b[0]</code> through <code>b[</code><i>k</i><code>-1]</code>,
- 068 * leaving elements <code>b[</code><i>k</i><code>]</code> through
- 069 * <code>b[b.length-1]</code> unaffected.
- 070 *
- 071 * <p> The <code>read(b)</code> method for class <code>InputStream</code>
- 072 * has the same effect as: <pre><code> read(b, 0, b.length) </code></pre>
- 073 *
- 074 * @param b the buffer into which the data is read.
- 075 * @return the total number of bytes read into the buffer, or
- 076 * <code>-1</code> is there is no more data because the end of
- 077 * the stream has been reached.
- 078 * @exception IOException If the first byte cannot be read for any reason
- 079 * other than the end of the file, if the input stream has been closed, or
- 080 * if some other I/O error occurs.
- 081 * @exception NullPointerException if <code>b</code> is <code>null</code>.
- 082 * @see java.io.InputStream#read(byte[], int, int)
- 083 */
- 084 public int read(byte b[]) throws IOException {
- 085 return read(b, 0, b.length);
- 086 }
- 087
- 088 /**
- 089 * Reads up to <code>len</code> bytes of data from the input stream into
- 090 * an array of bytes. An attempt is made to read as many as
- 091 * <code>len</code> bytes, but a smaller number may be read.
- 092 * The number of bytes actually read is returned as an integer.
- 093 *
- 094 * <p> This method blocks until input data is available, end of file is
- 095 * detected, or an exception is thrown.
- 096 *
- 097 * <p> If <code>len</code> is zero, then no bytes are read and
- 098 * <code>0</code> is returned; otherwise, there is an attempt to read at
- 099 * least one byte. If no byte is available because the stream is at end of
- 100 * file, the value <code>-1</code> is returned; otherwise, at least one
- 101 * byte is read and stored into <code>b</code>.
- 102 *
- 103 * <p> The first byte read is stored into element <code>b[off]</code>, the
- 104 * next one into <code>b[off+1]</code>, and so on. The number of bytes read
- 105 * is, at most, equal to <code>len</code>. Let <i>k</i> be the number of
- 106 * bytes actually read; these bytes will be stored in elements
- 107 * <code>b[off]</code> through <code>b[off+</code><i>k</i><code>-1]</code>,
- 108 * leaving elements <code>b[off+</code><i>k</i><code>]</code> through
- 109 * <code>b[off+len-1]</code> unaffected.
- 110 *
- 111 * <p> In every case, elements <code>b[0]</code> through
- 112 * <code>b[off]</code> and elements <code>b[off+len]</code> through
- 113 * <code>b[b.length-1]</code> are unaffected.
- 114 *
- 115 * <p> The <code>read(b,</code> <code>off,</code> <code>len)</code> method
- 116 * for class <code>InputStream</code> simply calls the method
- 117 * <code>read()</code> repeatedly. If the first such call results in an
- 118 * <code>IOException</code>, that exception is returned from the call to
- 119 * the <code>read(b,</code> <code>off,</code> <code>len)</code> method. If
- 120 * any subsequent call to <code>read()</code> results in a
- 121 * <code>IOException</code>, the exception is caught and treated as if it
- 122 * were end of file; the bytes read up to that point are stored into
- 123 * <code>b</code> and the number of bytes read before the exception
- 124 * occurred is returned. The default implementation of this method blocks
- 125 * until the requested amount of input data <code>len</code> has been read,
- 126 * end of file is detected, or an exception is thrown. Subclasses are encouraged
- 127 * to provide a more efficient implementation of this method.
- 128 *
- 129 * @param b the buffer into which the data is read.
- 130 * @param off the start offset in array <code>b</code>
- 131 * at which the data is written.
- 132 * @param len the maximum number of bytes to read.
- 133 * @return the total number of bytes read into the buffer, or
- 134 * <code>-1</code> if there is no more data because the end of
- 135 * the stream has been reached.
- 136 * @exception IOException If the first byte cannot be read for any reason
- 137 * other than end of file, or if the input stream has been closed, or if
- 138 * some other I/O error occurs.
- 139 * @exception NullPointerException If <code>b</code> is <code>null</code>.
- 140 * @exception IndexOutOfBoundsException If <code>off</code> is negative,
- 141 * <code>len</code> is negative, or <code>len</code> is greater than
- 142 * <code>b.length - off</code>
- 143 * @see java.io.InputStream#read()
- 144 */
- 145 public int read(byte b[], int off, int len) throws IOException {
- 146 if (b == null) {
- 147 throw new NullPointerException();
- 148 } else if (off < 0 || len < 0 || len > b.length - off) {
- 149 throw new IndexOutOfBoundsException();
- 150 } else if (len == 0) {
- 151 return 0;
- 152 }
- 153
- 154 int c = read();
- 155 if (c == -1) {
- 156 return -1;
- 157 }
- 158 b[off] = (byte)c;
- 159
- 160 int i = 1;
- 161 try {
- 162 for (; i < len ; i++) {
- 163 c = read();
- 164 if (c == -1) {
- 165 break;
- 166 }
- 167 b[off + i] = (byte)c;
- 168 }
- 169 } catch (IOException ee) {
- 170 }
- 171 return i;
- 172 }
- 173
- 174 /**
- 175 * Skips over and discards <code>n</code> bytes of data from this input
- 176 * stream. The <code>skip</code> method may, for a variety of reasons, end
- 177 * up skipping over some smaller number of bytes, possibly <code>0</code>.
- 178 * This may result from any of a number of conditions; reaching end of file
- 179 * before <code>n</code> bytes have been skipped is only one possibility.
- 180 * The actual number of bytes skipped is returned. If <code>n</code> is
- 181 * negative, no bytes are skipped.
- 182 *
- 183 * <p> The <code>skip</code> method of this class creates a
- 184 * byte array and then repeatedly reads into it until <code>n</code> bytes
- 185 * have been read or the end of the stream has been reached. Subclasses are
- 186 * encouraged to provide a more efficient implementation of this method.
- 187 * For instance, the implementation may depend on the ability to seek.
- 188 *
- 189 * @param n the number of bytes to be skipped.
- 190 * @return the actual number of bytes skipped.
- 191 * @exception IOException if the stream does not support seek,
- 192 * or if some other I/O error occurs.
- 193 */
- 194 public long skip(long n) throws IOException {
- 195
- 196 long remaining = n;
- 197 int nr;
- 198 if (skipBuffer == null)
- 199 skipBuffer = new byte[SKIP_BUFFER_SIZE];
- 200
- 201 byte[] localSkipBuffer = skipBuffer;
- 202
- 203 if (n <= 0) {
- 204 return 0;
- 205 }
- 206
- 207 while (remaining > 0) {
- 208 nr = read(localSkipBuffer, 0,
- 209 (int) Math.min(SKIP_BUFFER_SIZE, remaining));
- 210 if (nr < 0) {
- 211 break;
- 212 }
- 213 remaining -= nr;
- 214 }
- 215
- 216 return n - remaining;
- 217 }
- 218
- 219 /**
- 220 * Returns an estimate of the number of bytes that can be read (or
- 221 * skipped over) from this input stream without blocking by the next
- 222 * invocation of a method for this input stream. The next invocation
- 223 * might be the same thread or another thread. A single read or skip of this
- 224 * many bytes will not block, but may read or skip fewer bytes.
- 225 *
- 226 * <p> Note that while some implementations of {@code InputStream} will return
- 227 * the total number of bytes in the stream, many will not. It is
- 228 * never correct to use the return value of this method to allocate
- 229 * a buffer intended to hold all data in this stream.
- 230 *
- 231 * <p> A subclass' implementation of this method may choose to throw an
- 232 * {@link IOException} if this input stream has been closed by
- 233 * invoking the {@link #close()} method.
- 234 *
- 235 * <p> The {@code available} method for class {@code InputStream} always
- 236 * returns {@code 0}.
- 237 *
- 238 * <p> This method should be overridden by subclasses.
- 239 *
- 240 * @return an estimate of the number of bytes that can be read (or skipped
- 241 * over) from this input stream without blocking or {@code 0} when
- 242 * it reaches the end of the input stream.
- 243 * @exception IOException if an I/O error occurs.
- 244 */
- 245 public int available() throws IOException {
- 246 return 0;
- 247 }
- 248
- 249 /**
- 250 * Closes this input stream and releases any system resources associated
- 251 * with the stream.
- 252 *
- 253 * <p> The <code>close</code> method of <code>InputStream</code> does
- 254 * nothing.
- 255 *
- 256 * @exception IOException if an I/O error occurs.
- 257 */
- 258 public void close() throws IOException {}
- 259
- 260 /**
- 261 * Marks the current position in this input stream. A subsequent call to
- 262 * the <code>reset</code> method repositions this stream at the last marked
- 263 * position so that subsequent reads re-read the same bytes.
- 264 *
- 265 * <p> The <code>readlimit</code> arguments tells this input stream to
- 266 * allow that many bytes to be read before the mark position gets
- 267 * invalidated.
- 268 *
- 269 * <p> The general contract of <code>mark</code> is that, if the method
- 270 * <code>markSupported</code> returns <code>true</code>, the stream somehow
- 271 * remembers all the bytes read after the call to <code>mark</code> and
- 272 * stands ready to supply those same bytes again if and whenever the method
- 273 * <code>reset</code> is called. However, the stream is not required to
- 274 * remember any data at all if more than <code>readlimit</code> bytes are
- 275 * read from the stream before <code>reset</code> is called.
- 276 *
- 277 * <p> Marking a closed stream should not have any effect on the stream.
- 278 *
- 279 * <p> The <code>mark</code> method of <code>InputStream</code> does
- 280 * nothing.
- 281 *
- 282 * @param readlimit the maximum limit of bytes that can be read before
- 283 * the mark position becomes invalid.
- 284 * @see java.io.InputStream#reset()
- 285 */
- 286 public synchronized void mark(int readlimit) {}
- 287
- 288 /**
- 289 * Repositions this stream to the position at the time the
- 290 * <code>mark</code> method was last called on this input stream.
- 291 *
- 292 * <p> The general contract of <code>reset</code> is:
- 293 *
- 294 * <p><ul>
- 295 *
- 296 * <li> If the method <code>markSupported</code> returns
- 297 * <code>true</code>, then:
- 298 *
- 299 * <ul><li> If the method <code>mark</code> has not been called since
- 300 * the stream was created, or the number of bytes read from the stream
- 301 * since <code>mark</code> was last called is larger than the argument
- 302 * to <code>mark</code> at that last call, then an
- 303 * <code>IOException</code> might be thrown.
- 304 *
- 305 * <li> If such an <code>IOException</code> is not thrown, then the
- 306 * stream is reset to a state such that all the bytes read since the
- 307 * most recent call to <code>mark</code> (or since the start of the
- 308 * file, if <code>mark</code> has not been called) will be resupplied
- 309 * to subsequent callers of the <code>read</code> method, followed by
- 310 * any bytes that otherwise would have been the next input data as of
- 311 * the time of the call to <code>reset</code>. </ul>
- 312 *
- 313 * <li> If the method <code>markSupported</code> returns
- 314 * <code>false</code>, then:
- 315 *
- 316 * <ul><li> The call to <code>reset</code> may throw an
- 317 * <code>IOException</code>.
- 318 *
- 319 * <li> If an <code>IOException</code> is not thrown, then the stream
- 320 * is reset to a fixed state that depends on the particular type of the
- 321 * input stream and how it was created. The bytes that will be supplied
- 322 * to subsequent callers of the <code>read</code> method depend on the
- 323 * particular type of the input stream. </ul></ul>
- 324 *
- 325 * <p>The method <code>reset</code> for class <code>InputStream</code>
- 326 * does nothing except throw an <code>IOException</code>.
- 327 *
- 328 * @exception IOException if this stream has not been marked or if the
- 329 * mark has been invalidated.
- 330 * @see java.io.InputStream#mark(int)
- 331 * @see java.io.IOException
- 332 */
- 333 public synchronized void reset() throws IOException {
- 334 throw new IOException("mark/reset not supported");
- 335 }
- 336
- 337 /**
- 338 * Tests if this input stream supports the <code>mark</code> and
- 339 * <code>reset</code> methods. Whether or not <code>mark</code> and
- 340 * <code>reset</code> are supported is an invariant property of a
- 341 * particular input stream instance. The <code>markSupported</code> method
- 342 * of <code>InputStream</code> returns <code>false</code>.
- 343 *
- 344 * @return <code>true</code> if this stream instance supports the mark
- 345 * and reset methods; <code>false</code> otherwise.
- 346 * @see java.io.InputStream#mark(int)
- 347 * @see java.io.InputStream#reset()
- 348 */
- 349 public boolean markSupported() {
- 350 return false;
- 351 }
- 352
- 353}
