* @return 0 if no further bytes are available. Otherwise returns 1,
* which suggests (but does not guarantee) that additional bytes are
* available.
- * @throws IOException
- * If an error occurs.
+ * @throws IOException if this stream is closed or an error occurs
*/
@Override
public int available() throws IOException {
return skipped;
}
- /**
- * Returns 0 if the {@code EOF} has been reached, otherwise returns 1.
- *
- * @return 0 after {@code EOF} of current entry, 1 otherwise.
- * @throws IOException
- * if an IOException occurs.
- */
@Override
public int available() throws IOException {
if (closed) {
throw new IOException(Messages.getString("archive.1E")); //$NON-NLS-1$
}
+ // The InflaterInputStream contract says we must only return 0 or 1.
return (currentEntry == null || inRead < currentEntry.size) ? 1 : 0;
}
return i;
}
- /**
- * Returns the number of bytes available without blocking.
- *
- * @return the number of bytes available, currently zero.
- * @throws IOException
- * if an error occurs
- */
@Override
public int available() throws IOException {
return 0;
return false;
}
}
-
}
/**
- * Returns the number of bytes that are available before this stream will
- * block. This method returns the number of bytes available in the buffer
- * plus those available in the source stream.
+ * Returns an estimated number of bytes that can be read or skipped without blocking for more
+ * input. This method returns the number of bytes available in the buffer
+ * plus those available in the source stream, but see {@link InputStream#available} for
+ * important caveats.
*
- * @return the number of bytes available before blocking.
- * @throws IOException
- * if this stream is closed.
+ * @return the estimated number of bytes available
+ * @throws IOException if this stream is closed or an error occurs
*/
@Override
public synchronized int available() throws IOException {
}
/**
- * Returns the number of bytes that are available before this stream will
- * block. This method returns the number of bytes yet to be read from the
- * source byte array.
+ * Returns the number of remaining bytes.
*
- * @return the number of bytes available before blocking.
+ * @return {@code count - pos}
*/
@Override
public synchronized int available() {
this(null == fileName ? (File) null : new File(fileName));
}
- /**
- * Returns the number of bytes that are available before this stream will
- * block. This method always returns the size of the file minus the current
- * position.
- *
- * @return the number of bytes available before blocking.
- * @throws IOException
- * if an error occurs in this stream.
- */
@Override
public int available() throws IOException {
openCheck();
this.in = in;
}
- /**
- * Returns the number of bytes that are available before this stream will
- * block.
- *
- * @return the number of bytes available before blocking.
- * @throws IOException
- * if an error occurs in this stream.
- */
@Override
public int available() throws IOException {
return in.available();
}
/**
- * Returns the number of bytes that are available before this stream will
- * block. This implementation always returns 0. Subclasses should override
- * and indicate the correct number of bytes available.
+ * Returns an estimated number of bytes that can be read or skipped without blocking for more
+ * input.
*
- * @return the number of bytes available before blocking.
- * @throws IOException
- * if an error occurs in this stream.
+ * <p>Note that this method provides such a weak guarantee that it is not very useful in
+ * practice.
+ *
+ * <p>Firstly, the guarantee is "without blocking for more input" rather than "without
+ * blocking": a read may still block waiting for I/O to complete — the guarantee is
+ * merely that it won't have to wait indefinitely for data to be written. The result of this
+ * method should not be used as a license to do I/O on a thread that shouldn't be blocked.
+ *
+ * <p>Secondly, the result is a
+ * conservative estimate and may be significantly smaller than the actual number of bytes
+ * available. In particular, an implementation that always returns 0 would be correct.
+ * In general, callers should only use this method if they'd be satisfied with
+ * treating the result as a boolean yes or no answer to the question "is there definitely
+ * data ready?".
+ *
+ * <p>Thirdly, the fact that a given number of bytes is "available" does not guarantee that a
+ * read or skip will actually read or skip that many bytes: they may read or skip fewer.
+ *
+ * <p>It is particularly important to realize that you <i>must not</i> use this method to
+ * size a container and assume that you can read the entirety of the stream without needing
+ * to resize the container. Such callers should probably write everything they read to a
+ * {@link ByteArrayOutputStream} and convert that to a byte array. Alternatively, if you're
+ * reading from a file, {@link File#length} returns the current length of the file (though
+ * assuming the file's length can't change may be incorrect, reading a file is inherently
+ * racy).
+ *
+ * <p>The default implementation of this method in {@code InputStream} always returns 0.
+ * Subclasses should override this method if they are able to indicate the number of bytes
+ * available.
+ *
+ * @return the estimated number of bytes available
+ * @throws IOException if this stream is closed or an error occurs
*/
public int available() throws IOException {
return 0;
}
/**
- * Skips at most {@code n} bytes in this stream. It does nothing and returns
- * 0 if {@code n} is negative. Less than {@code n} characters are skipped if
- * the end of this stream is reached before the operation completes.
- * <p>
- * This default implementation reads {@code n} bytes into a temporary
+ * Skips at most {@code n} bytes in this stream. This method does nothing and returns
+ * 0 if {@code n} is negative.
+ *
+ * <p>Note the "at most" in the description of this method: this method may choose to skip
+ * fewer bytes than requested. Callers should <i>always</i> check the return value.
+ *
+ * <p>This default implementation reads bytes into a temporary
* buffer. Concrete subclasses should provide their own implementation.
*
- * @param n
- * the number of bytes to skip.
+ * @param n the number of bytes to skip.
* @return the number of bytes actually skipped.
* @throws IOException
* if this stream is closed or another IOException occurs.
}
/**
- * Returns the number of bytes that are available before this stream will
- * block.
- * <p>
- * Note: The source stream may just be a sequence of {@code "\r\n"} bytes
+ * {@inheritDoc}
+ *
+ * <p>Note that the source stream may just be a sequence of {@code "\r\n"} bytes
* which are converted into {@code '\n'} by this stream. Therefore,
* {@code available} returns only {@code in.available() / 2} bytes as
* result.
- *
- * @return the guaranteed number of bytes available before blocking.
- * @throws IOException
- * if an error occurs in this stream.
*/
@Override
public int available() throws IOException {
primitiveData = emptyStream;
}
- /**
- * Returns the number of bytes of primitive data that can be read from this
- * stream without blocking. This method should not be used at any arbitrary
- * position; just when reading primitive data types (int, char etc).
- *
- * @return the number of available primitive data bytes.
- * @throws IOException
- * if any I/O problem occurs while computing the available
- * bytes.
- */
@Override
public int available() throws IOException {
// returns 0 if next data is an object, or N if reading primitive types
}
/**
- * Returns the number of bytes that are available before this stream will
- * block. This implementation returns the number of bytes written to this
- * pipe that have not been read yet.
+ * {@inheritDoc}
*
- * @return the number of bytes available before blocking.
- * @throws IOException
- * if an error occurs in this stream.
+ * <p>Unlike most streams, {@code PipedInputStream} returns 0 rather than throwing
+ * {@code IOException} if the stream has been closed. Unconnected and broken pipes also
+ * return 0.
+ *
+ * @throws IOException if an I/O error occurs
*/
@Override
public synchronized int available() throws IOException {
pos = size;
}
- /**
- * Returns the number of bytes that are available before this stream will
- * block. This is the sum of the bytes available in the pushback buffer and
- * those available from the source stream.
- *
- * @return the number of bytes available before blocking.
- * @throws IOException
- * if this stream is closed or an I/O error occurs in the source
- * stream.
- */
@Override
public int available() throws IOException {
if (buf == null) {
}
}
- /**
- * Returns the number of bytes that are available before the current input stream will
- * block.
- *
- * @return the number of bytes available in the current input stream before blocking.
- * @throws IOException
- * if an I/O error occurs in the current input stream.
- */
@Override
public int available() throws IOException {
if (e != null && in != null) {
count = str.length();
}
- /**
- * Returns the number of bytes that are available before this stream will
- * block.
- *
- * @return the number of bytes available before blocking.
- */
@Override
public synchronized int available() {
return count - pos;
this.inStream = inStream;
}
- /**
- * @see java.io.InputStream#available()
- * method documentation for more info
- */
+ @Override
public int available() throws IOException {
return (bar - pos) + inStream.available();
}
- /**
- * @see java.io.InputStream#close()
- * method documentation for more info
- */
+ @Override
public void close() throws IOException {
inStream.close();
}
- /**
- * @see java.io.InputStream#mark(int readlimit)
- * method documentation for more info
- */
+ @Override
public void mark(int readlimit) {
if (pos < 0) {
pos = 0;
}
}
- /**
- * @see java.io.InputStream#markSupported()
- * method documentation for more info
- */
+ @Override
public boolean markSupported() {
return true;
}
return inStream.read();
}
- /**
- * @see java.io.InputStream#read(byte[] b)
- * method documentation for more info
- */
+ @Override
public int read(byte[] b) throws IOException {
return read(b, 0, b.length);
}
- /**
- * @see java.io.InputStream#read(byte[] b, int off, int len)
- * method documentation for more info
- */
+ @Override
public int read(byte[] b, int off, int len) throws IOException {
int read_b;
int i;
return i;
}
- /**
- * @see java.io.InputStream#reset()
- * method documentation for more info
- */
+ @Override
public void reset() throws IOException {
if (pos >= 0) {
pos = (end + 1) % BUFF_SIZE;
}
}
- /**
- * @see java.io.InputStream#skip(long n)
- * method documentation for more info
- */
+ @Override
public long skip(long n) throws IOException {
if (pos >= 0) {
long i = 0;
}
}
}
-
-
-
this.pos = 0;
}
- /**
- * Return number of available bytes for reading.
- * @return available input bytes
- */
-
+ @Override
public int available() throws IOException {
int ret = blob.size - pos;
return (ret < 0) ? 0 : ret;
this.in = in;
}
- /**
- * Returns the number of bytes available for reading.
- */
@Override
public int available() throws IOException {
// in assumption that the buffer has been set
return bytik;
}
}
-
*/
public abstract class SSLInputStream extends InputStream {
- /**
- * @see java.io.InputStream#available()
- */
@Override
public abstract int available() throws IOException;
@Override
public abstract int read() throws IOException;
- /**
- * @see java.io.InputStream#skip(long)
- */
@Override
public long skip(long n) throws IOException {
long skept = n;
return res;
}
- /**
- * @see java.io.InputStream#read(byte[],int,int)
- */
@Override
public int read(byte[] b, int off, int len) throws IOException {
int read_b;