1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/rt/emul/mini/src/main/java/java/io/InputStream.java Tue Feb 26 16:54:16 2013 +0100
1.3 @@ -0,0 +1,370 @@
1.4 +/*
1.5 + * Copyright (c) 1994, 2006, Oracle and/or its affiliates. All rights reserved.
1.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.7 + *
1.8 + * This code is free software; you can redistribute it and/or modify it
1.9 + * under the terms of the GNU General Public License version 2 only, as
1.10 + * published by the Free Software Foundation. Oracle designates this
1.11 + * particular file as subject to the "Classpath" exception as provided
1.12 + * by Oracle in the LICENSE file that accompanied this code.
1.13 + *
1.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
1.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.17 + * version 2 for more details (a copy is included in the LICENSE file that
1.18 + * accompanied this code).
1.19 + *
1.20 + * You should have received a copy of the GNU General Public License version
1.21 + * 2 along with this work; if not, write to the Free Software Foundation,
1.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.23 + *
1.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
1.25 + * or visit www.oracle.com if you need additional information or have any
1.26 + * questions.
1.27 + */
1.28 +
1.29 +package java.io;
1.30 +
1.31 +/**
1.32 + * This abstract class is the superclass of all classes representing
1.33 + * an input stream of bytes.
1.34 + *
1.35 + * <p> Applications that need to define a subclass of <code>InputStream</code>
1.36 + * must always provide a method that returns the next byte of input.
1.37 + *
1.38 + * @author Arthur van Hoff
1.39 + * @see java.io.BufferedInputStream
1.40 + * @see java.io.ByteArrayInputStream
1.41 + * @see java.io.DataInputStream
1.42 + * @see java.io.FilterInputStream
1.43 + * @see java.io.InputStream#read()
1.44 + * @see java.io.OutputStream
1.45 + * @see java.io.PushbackInputStream
1.46 + * @since JDK1.0
1.47 + */
1.48 +public abstract class InputStream implements Closeable {
1.49 +
1.50 + // SKIP_BUFFER_SIZE is used to determine the size of skipBuffer
1.51 + private static final int SKIP_BUFFER_SIZE = 2048;
1.52 + // skipBuffer is initialized in skip(long), if needed.
1.53 + private static byte[] skipBuffer;
1.54 +
1.55 + /**
1.56 + * Reads the next byte of data from the input stream. The value byte is
1.57 + * returned as an <code>int</code> in the range <code>0</code> to
1.58 + * <code>255</code>. If no byte is available because the end of the stream
1.59 + * has been reached, the value <code>-1</code> is returned. This method
1.60 + * blocks until input data is available, the end of the stream is detected,
1.61 + * or an exception is thrown.
1.62 + *
1.63 + * <p> A subclass must provide an implementation of this method.
1.64 + *
1.65 + * @return the next byte of data, or <code>-1</code> if the end of the
1.66 + * stream is reached.
1.67 + * @exception IOException if an I/O error occurs.
1.68 + */
1.69 + public abstract int read() throws IOException;
1.70 +
1.71 + /**
1.72 + * Reads some number of bytes from the input stream and stores them into
1.73 + * the buffer array <code>b</code>. The number of bytes actually read is
1.74 + * returned as an integer. This method blocks until input data is
1.75 + * available, end of file is detected, or an exception is thrown.
1.76 + *
1.77 + * <p> If the length of <code>b</code> is zero, then no bytes are read and
1.78 + * <code>0</code> is returned; otherwise, there is an attempt to read at
1.79 + * least one byte. If no byte is available because the stream is at the
1.80 + * end of the file, the value <code>-1</code> is returned; otherwise, at
1.81 + * least one byte is read and stored into <code>b</code>.
1.82 + *
1.83 + * <p> The first byte read is stored into element <code>b[0]</code>, the
1.84 + * next one into <code>b[1]</code>, and so on. The number of bytes read is,
1.85 + * at most, equal to the length of <code>b</code>. Let <i>k</i> be the
1.86 + * number of bytes actually read; these bytes will be stored in elements
1.87 + * <code>b[0]</code> through <code>b[</code><i>k</i><code>-1]</code>,
1.88 + * leaving elements <code>b[</code><i>k</i><code>]</code> through
1.89 + * <code>b[b.length-1]</code> unaffected.
1.90 + *
1.91 + * <p> The <code>read(b)</code> method for class <code>InputStream</code>
1.92 + * has the same effect as: <pre><code> read(b, 0, b.length) </code></pre>
1.93 + *
1.94 + * @param b the buffer into which the data is read.
1.95 + * @return the total number of bytes read into the buffer, or
1.96 + * <code>-1</code> if there is no more data because the end of
1.97 + * the stream has been reached.
1.98 + * @exception IOException If the first byte cannot be read for any reason
1.99 + * other than the end of the file, if the input stream has been closed, or
1.100 + * if some other I/O error occurs.
1.101 + * @exception NullPointerException if <code>b</code> is <code>null</code>.
1.102 + * @see java.io.InputStream#read(byte[], int, int)
1.103 + */
1.104 + public int read(byte b[]) throws IOException {
1.105 + return read(b, 0, b.length);
1.106 + }
1.107 +
1.108 + /**
1.109 + * Reads up to <code>len</code> bytes of data from the input stream into
1.110 + * an array of bytes. An attempt is made to read as many as
1.111 + * <code>len</code> bytes, but a smaller number may be read.
1.112 + * The number of bytes actually read is returned as an integer.
1.113 + *
1.114 + * <p> This method blocks until input data is available, end of file is
1.115 + * detected, or an exception is thrown.
1.116 + *
1.117 + * <p> If <code>len</code> is zero, then no bytes are read and
1.118 + * <code>0</code> is returned; otherwise, there is an attempt to read at
1.119 + * least one byte. If no byte is available because the stream is at end of
1.120 + * file, the value <code>-1</code> is returned; otherwise, at least one
1.121 + * byte is read and stored into <code>b</code>.
1.122 + *
1.123 + * <p> The first byte read is stored into element <code>b[off]</code>, the
1.124 + * next one into <code>b[off+1]</code>, and so on. The number of bytes read
1.125 + * is, at most, equal to <code>len</code>. Let <i>k</i> be the number of
1.126 + * bytes actually read; these bytes will be stored in elements
1.127 + * <code>b[off]</code> through <code>b[off+</code><i>k</i><code>-1]</code>,
1.128 + * leaving elements <code>b[off+</code><i>k</i><code>]</code> through
1.129 + * <code>b[off+len-1]</code> unaffected.
1.130 + *
1.131 + * <p> In every case, elements <code>b[0]</code> through
1.132 + * <code>b[off]</code> and elements <code>b[off+len]</code> through
1.133 + * <code>b[b.length-1]</code> are unaffected.
1.134 + *
1.135 + * <p> The <code>read(b,</code> <code>off,</code> <code>len)</code> method
1.136 + * for class <code>InputStream</code> simply calls the method
1.137 + * <code>read()</code> repeatedly. If the first such call results in an
1.138 + * <code>IOException</code>, that exception is returned from the call to
1.139 + * the <code>read(b,</code> <code>off,</code> <code>len)</code> method. If
1.140 + * any subsequent call to <code>read()</code> results in a
1.141 + * <code>IOException</code>, the exception is caught and treated as if it
1.142 + * were end of file; the bytes read up to that point are stored into
1.143 + * <code>b</code> and the number of bytes read before the exception
1.144 + * occurred is returned. The default implementation of this method blocks
1.145 + * until the requested amount of input data <code>len</code> has been read,
1.146 + * end of file is detected, or an exception is thrown. Subclasses are encouraged
1.147 + * to provide a more efficient implementation of this method.
1.148 + *
1.149 + * @param b the buffer into which the data is read.
1.150 + * @param off the start offset in array <code>b</code>
1.151 + * at which the data is written.
1.152 + * @param len the maximum number of bytes to read.
1.153 + * @return the total number of bytes read into the buffer, or
1.154 + * <code>-1</code> if there is no more data because the end of
1.155 + * the stream has been reached.
1.156 + * @exception IOException If the first byte cannot be read for any reason
1.157 + * other than end of file, or if the input stream has been closed, or if
1.158 + * some other I/O error occurs.
1.159 + * @exception NullPointerException If <code>b</code> is <code>null</code>.
1.160 + * @exception IndexOutOfBoundsException If <code>off</code> is negative,
1.161 + * <code>len</code> is negative, or <code>len</code> is greater than
1.162 + * <code>b.length - off</code>
1.163 + * @see java.io.InputStream#read()
1.164 + */
1.165 + public int read(byte b[], int off, int len) throws IOException {
1.166 + if (b == null) {
1.167 + throw new NullPointerException();
1.168 + } else if (off < 0 || len < 0 || len > b.length - off) {
1.169 + throw new IndexOutOfBoundsException();
1.170 + } else if (len == 0) {
1.171 + return 0;
1.172 + }
1.173 +
1.174 + int c = read();
1.175 + if (c == -1) {
1.176 + return -1;
1.177 + }
1.178 + b[off] = (byte)c;
1.179 +
1.180 + int i = 1;
1.181 + try {
1.182 + for (; i < len ; i++) {
1.183 + c = read();
1.184 + if (c == -1) {
1.185 + break;
1.186 + }
1.187 + b[off + i] = (byte)c;
1.188 + }
1.189 + } catch (IOException ee) {
1.190 + }
1.191 + return i;
1.192 + }
1.193 +
1.194 + /**
1.195 + * Skips over and discards <code>n</code> bytes of data from this input
1.196 + * stream. The <code>skip</code> method may, for a variety of reasons, end
1.197 + * up skipping over some smaller number of bytes, possibly <code>0</code>.
1.198 + * This may result from any of a number of conditions; reaching end of file
1.199 + * before <code>n</code> bytes have been skipped is only one possibility.
1.200 + * The actual number of bytes skipped is returned. If <code>n</code> is
1.201 + * negative, no bytes are skipped.
1.202 + *
1.203 + * <p> The <code>skip</code> method of this class creates a
1.204 + * byte array and then repeatedly reads into it until <code>n</code> bytes
1.205 + * have been read or the end of the stream has been reached. Subclasses are
1.206 + * encouraged to provide a more efficient implementation of this method.
1.207 + * For instance, the implementation may depend on the ability to seek.
1.208 + *
1.209 + * @param n the number of bytes to be skipped.
1.210 + * @return the actual number of bytes skipped.
1.211 + * @exception IOException if the stream does not support seek,
1.212 + * or if some other I/O error occurs.
1.213 + */
1.214 + public long skip(long n) throws IOException {
1.215 +
1.216 + long remaining = n;
1.217 + int nr;
1.218 + if (skipBuffer == null)
1.219 + skipBuffer = new byte[SKIP_BUFFER_SIZE];
1.220 +
1.221 + byte[] localSkipBuffer = skipBuffer;
1.222 +
1.223 + if (n <= 0) {
1.224 + return 0;
1.225 + }
1.226 +
1.227 + while (remaining > 0) {
1.228 + nr = read(localSkipBuffer, 0,
1.229 + (int) Math.min(SKIP_BUFFER_SIZE, remaining));
1.230 + if (nr < 0) {
1.231 + break;
1.232 + }
1.233 + remaining -= nr;
1.234 + }
1.235 +
1.236 + return n - remaining;
1.237 + }
1.238 +
1.239 + /**
1.240 + * Returns an estimate of the number of bytes that can be read (or
1.241 + * skipped over) from this input stream without blocking by the next
1.242 + * invocation of a method for this input stream. The next invocation
1.243 + * might be the same thread or another thread. A single read or skip of this
1.244 + * many bytes will not block, but may read or skip fewer bytes.
1.245 + *
1.246 + * <p> Note that while some implementations of {@code InputStream} will return
1.247 + * the total number of bytes in the stream, many will not. It is
1.248 + * never correct to use the return value of this method to allocate
1.249 + * a buffer intended to hold all data in this stream.
1.250 + *
1.251 + * <p> A subclass' implementation of this method may choose to throw an
1.252 + * {@link IOException} if this input stream has been closed by
1.253 + * invoking the {@link #close()} method.
1.254 + *
1.255 + * <p> The {@code available} method for class {@code InputStream} always
1.256 + * returns {@code 0}.
1.257 + *
1.258 + * <p> This method should be overridden by subclasses.
1.259 + *
1.260 + * @return an estimate of the number of bytes that can be read (or skipped
1.261 + * over) from this input stream without blocking or {@code 0} when
1.262 + * it reaches the end of the input stream.
1.263 + * @exception IOException if an I/O error occurs.
1.264 + */
1.265 + public int available() throws IOException {
1.266 + return 0;
1.267 + }
1.268 +
1.269 + /**
1.270 + * Closes this input stream and releases any system resources associated
1.271 + * with the stream.
1.272 + *
1.273 + * <p> The <code>close</code> method of <code>InputStream</code> does
1.274 + * nothing.
1.275 + *
1.276 + * @exception IOException if an I/O error occurs.
1.277 + */
1.278 + public void close() throws IOException {}
1.279 +
1.280 + /**
1.281 + * Marks the current position in this input stream. A subsequent call to
1.282 + * the <code>reset</code> method repositions this stream at the last marked
1.283 + * position so that subsequent reads re-read the same bytes.
1.284 + *
1.285 + * <p> The <code>readlimit</code> arguments tells this input stream to
1.286 + * allow that many bytes to be read before the mark position gets
1.287 + * invalidated.
1.288 + *
1.289 + * <p> The general contract of <code>mark</code> is that, if the method
1.290 + * <code>markSupported</code> returns <code>true</code>, the stream somehow
1.291 + * remembers all the bytes read after the call to <code>mark</code> and
1.292 + * stands ready to supply those same bytes again if and whenever the method
1.293 + * <code>reset</code> is called. However, the stream is not required to
1.294 + * remember any data at all if more than <code>readlimit</code> bytes are
1.295 + * read from the stream before <code>reset</code> is called.
1.296 + *
1.297 + * <p> Marking a closed stream should not have any effect on the stream.
1.298 + *
1.299 + * <p> The <code>mark</code> method of <code>InputStream</code> does
1.300 + * nothing.
1.301 + *
1.302 + * @param readlimit the maximum limit of bytes that can be read before
1.303 + * the mark position becomes invalid.
1.304 + * @see java.io.InputStream#reset()
1.305 + */
1.306 + public synchronized void mark(int readlimit) {}
1.307 +
1.308 + /**
1.309 + * Repositions this stream to the position at the time the
1.310 + * <code>mark</code> method was last called on this input stream.
1.311 + *
1.312 + * <p> The general contract of <code>reset</code> is:
1.313 + *
1.314 + * <p><ul>
1.315 + *
1.316 + * <li> If the method <code>markSupported</code> returns
1.317 + * <code>true</code>, then:
1.318 + *
1.319 + * <ul><li> If the method <code>mark</code> has not been called since
1.320 + * the stream was created, or the number of bytes read from the stream
1.321 + * since <code>mark</code> was last called is larger than the argument
1.322 + * to <code>mark</code> at that last call, then an
1.323 + * <code>IOException</code> might be thrown.
1.324 + *
1.325 + * <li> If such an <code>IOException</code> is not thrown, then the
1.326 + * stream is reset to a state such that all the bytes read since the
1.327 + * most recent call to <code>mark</code> (or since the start of the
1.328 + * file, if <code>mark</code> has not been called) will be resupplied
1.329 + * to subsequent callers of the <code>read</code> method, followed by
1.330 + * any bytes that otherwise would have been the next input data as of
1.331 + * the time of the call to <code>reset</code>. </ul>
1.332 + *
1.333 + * <li> If the method <code>markSupported</code> returns
1.334 + * <code>false</code>, then:
1.335 + *
1.336 + * <ul><li> The call to <code>reset</code> may throw an
1.337 + * <code>IOException</code>.
1.338 + *
1.339 + * <li> If an <code>IOException</code> is not thrown, then the stream
1.340 + * is reset to a fixed state that depends on the particular type of the
1.341 + * input stream and how it was created. The bytes that will be supplied
1.342 + * to subsequent callers of the <code>read</code> method depend on the
1.343 + * particular type of the input stream. </ul></ul>
1.344 + *
1.345 + * <p>The method <code>reset</code> for class <code>InputStream</code>
1.346 + * does nothing except throw an <code>IOException</code>.
1.347 + *
1.348 + * @exception IOException if this stream has not been marked or if the
1.349 + * mark has been invalidated.
1.350 + * @see java.io.InputStream#mark(int)
1.351 + * @see java.io.IOException
1.352 + */
1.353 + public synchronized void reset() throws IOException {
1.354 + throw new IOException("mark/reset not supported");
1.355 + }
1.356 +
1.357 + /**
1.358 + * Tests if this input stream supports the <code>mark</code> and
1.359 + * <code>reset</code> methods. Whether or not <code>mark</code> and
1.360 + * <code>reset</code> are supported is an invariant property of a
1.361 + * particular input stream instance. The <code>markSupported</code> method
1.362 + * of <code>InputStream</code> returns <code>false</code>.
1.363 + *
1.364 + * @return <code>true</code> if this stream instance supports the mark
1.365 + * and reset methods; <code>false</code> otherwise.
1.366 + * @see java.io.InputStream#mark(int)
1.367 + * @see java.io.InputStream#reset()
1.368 + */
1.369 + public boolean markSupported() {
1.370 + return false;
1.371 + }
1.372 +
1.373 +}