What does Java's InputStream contract promise about read() and -1, short reads, blocking, available(), readAllBytes() and transferTo()?
answer
- 257 outcomes, not 256
- the count matters more than the buffer
- some input, not all input
- available() is an estimate
- neither closes, neither promises a flush
basics
~20 sInputStream.read() returns 0 to 255, or -1 at end of stream. read(byte[]) waits only for some input, so it may return fewer bytes than asked; loop. available() is an estimate. readAllBytes and transferTo read to the end without closing anything.
solid answer
~40 s`read()` returns an `int` because it needs 257 outcomes: the byte values 0 to 255 plus `-1` for end of stream. `read(byte[])` blocks until some input arrives, the stream ends or an error occurs, then returns how many bytes it stored, which may be fewer than the buffer holds, so you loop and use the count; `readNBytes(byte[], int, int)` runs that loop for you. `available()` only estimates what can be read without blocking: the base class always returns 0, and the Javadoc says it is never correct for sizing a buffer meant to hold all the data. `readAllBytes()` blocks to end of stream and is not meant for large inputs, and `transferTo()` may block indefinitely. Neither closes a stream, `transferTo` does not promise a flush, and an I/O error can leave a stream inconsistent.
code
java · 40 linesimport java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.util.Arrays;
public class CopyLoop {
static long copy(InputStream in, OutputStream out) throws IOException {
byte[] buffer = new byte[8192];
long total = 0;
int n;
while ((n = in.read(buffer)) != -1) {
out.write(buffer, 0, n);
total += n;
}
return total;
}
static byte[] readFrame(InputStream in, int size) throws IOException {
byte[] frame = new byte[size];
int n = in.readNBytes(frame, 0, size);
if (n < size) {
throw new IOException("stream ended after " + n + " of " + size + " bytes");
}
return frame;
}
public static void main(String[] args) throws IOException {
byte[] data = {1, 2, 3, 4, 5};
ByteArrayOutputStream out = new ByteArrayOutputStream();
System.out.println(copy(new ByteArrayInputStream(data), out));
System.out.println(Arrays.toString(readFrame(new ByteArrayInputStream(data), 4)));
try {
readFrame(new ByteArrayInputStream(data), 6);
} catch (IOException e) {
System.out.println(e.getMessage());
}
}
}go deeper
Recall that read() gives an int from 0 to 255, or -1 at end of stream, and that a buffer read returns a count you must use because it can be smaller than the buffer.
Explain the three outcomes of a buffer read: 0 for an empty request, -1 at the end, otherwise at least one byte. Say what blocks, why available() is only an estimate, and what readNBytes adds over one read.
Show the production judgment: framing code that assumes full reads passes in-memory tests and corrupts data on a socket. Bound whole-body reads on untrusted input, flush after transferTo, and close a stream promptly after an I/O error.
Weigh convenience against bounded resources: a team can standardise on streaming copies and size limits for untrusted input, keep whole-body reads for small known payloads, and enforce that split in review.
## What the contract covers `java.io.InputStream` is the abstract superclass of every **byte input stream**. A subclass must supply only one method, `read()`, which returns the next byte; the other read and skip methods and `transferTo` build on it and can be overridden for speed; `available`, `close`, `mark`, `reset` and `markSupported` do not. Two terms run through the contract. **End of stream** means the source has nothing further to give, as when a file is exhausted or a peer has closed its side of a connection. **Blocking** means the calling thread waits inside the call. ## Why `read()` returns an `int` A byte has 256 possible values, and `read()` needs a 257th outcome for "nothing left". A `byte` cannot hold 257 values, so the method returns an `int`: `0` to `255` for data and `-1` for end of stream. The classic bug is casting before the comparison. `(byte) in.read()` turns the data byte `0xFF` into `-1`, so the loop stops as though the stream had ended. On JDK 27, over the two bytes `{0xFF, 0x41}`, such a loop counts 0 bytes with the cast and 2 with an `int` check. Keep the result in an `int`, compare it, and cast afterwards. `Reader.read()` follows the same design with `0` to `65535` and `-1`. ## Short reads `read(byte[] b)` and `read(byte[] b, int off, int len)` read some bytes, up to the requested length, and return the count. The contract has three outcomes: - **Zero length requested:** no bytes are read and `0` is returned. - **At end of stream:** `-1` is returned. - **Otherwise:** at least one byte is stored, and at most the length requested. A **short read** is therefore legal and signals nothing. Write 3 bytes to a loopback socket, and an 8-byte `read` returns 3. `InputStream` leaves elements past the count unaffected, and `InflaterInputStream` documents them as undefined, so `out.write(buffer)` after a short read writes stale or undefined bytes; call `out.write(buffer, 0, n)`. Two details hide this in tests: - `ByteArrayInputStream.read(b, off, len)` returns the smaller of `len` and the bytes remaining, and its Javadoc says it cannot block, so in-memory tests see full reads. It also documents one exception to the list above: at its end with `len == 0` it returns `-1`. - The base class's own `read(b, off, len)` calls `read()` repeatedly until `len` bytes, end of file or an exception. An `IOException` after the first byte is caught and treated as end of file, so the call returns the bytes so far. When you need exactly `n` bytes, loop on `read` or call `readNBytes(b, off, len)`, which blocks until `len` bytes have been read, end of stream is detected or an exception is thrown. Fewer than `len` means the stream ended. `skip(n)` has the same shape: it may skip fewer, and `skipNBytes(n)`, from Java 12, is the exact form. ## What blocks | Call | Blocks until | Returns | |---|---|---| | `read()` | a byte, end of stream or an exception | `0` to `255`, or `-1` | | `read(b, off, len)` | some input, end of file or an exception | a count that may be under `len`, or `-1` | | `readNBytes(b, off, len)` | `len` bytes, end of stream or an exception | the count, possibly `0` | | `readAllBytes()` | all remaining bytes and end of stream, or an exception | an array, empty on later calls | | `transferTo(out)` | may block indefinitely on either stream | the bytes transferred, as a `long` | On `readAllBytes`, `readNBytes` and `transferTo`, what happens on an asynchronous close or a thread interrupt is documented as stream-specific and not specified, so do not count on an interrupt to free a blocked thread. A bounded wait has to come from the source, and `Socket.setSoTimeout` limits each underlying read, not the call: a silent peer raises `SocketTimeoutException`, while a peer trickling bytes keeps these calls blocked. ## What `available()` does not tell you `available()` returns an estimate of the bytes that can be read or skipped without blocking. - A single read or skip of that many bytes will not block, but may read or skip fewer. - Some implementations return the stream's total size and many do not. The Javadoc says it is never correct to use the value to allocate a buffer meant to hold all the data. - The base implementation always returns `0`: a subclass with five bytes left reports `0`. So `0` does not mean end of stream; a `read` that returns `-1` does. ## `readAllBytes()` and `transferTo()` Both arrived in Java 9, read to end of stream on success and close nothing. `InputStream.java` is byte-identical at JDK 25 and 27. - `readAllBytes()` holds everything in memory. Its Javadoc calls it intended for simple cases, not for large amounts of data, and it can throw `OutOfMemoryError`. `readNBytes(int len)`, from Java 11, keeps the allocation proportional to the bytes read, which `len` bounds. - `transferTo(out)` returns with the source at end of stream. The base implementation copies through a fixed 16 KB buffer and never calls `flush`, and the contract promises no flush: a transfer into a `BufferedOutputStream` moves 100 bytes and the sink holds 0 until the flush. What `flush` and `close` do is covered with closing and flushing streams. - After an I/O error, either can have read or written only part of the data and may leave a stream inconsistent; the Javadoc strongly recommends closing promptly.
- Why can a unit test over ByteArrayInputStream pass while the same read code fails on a socket?`ByteArrayInputStream.read(b, off, len)` returns the smaller of `len` and the bytes left, and it cannot block, so a buffer-sized read looks guaranteed. A socket stream can return what has arrived so far: over loopback, an 8-byte read returns 3 bytes after the peer writes 3. To expose the bug, test with a stream whose read returns one byte at a time.
- What does InputStream's default read(byte[], int, int) do if a later read() call throws IOException?It swallows that exception. The `@implSpec` says an `IOException` from any call after the first is caught and treated as end of file, and the bytes read so far are returned. A failure on the first byte does propagate. A subclass failing on its fourth byte returns 3 from an 8-byte read and throws on the next call.
- What do you call instead of InputStream.readAllBytes() when the input can be large or untrusted?`readNBytes(int len)` caps what you read: the Javadoc says its allocation is proportional to the bytes read, bounded by `len`, so a large limit is safe given enough memory. If you need no array at all, `transferTo(out)` moves the data onward. Check for more data afterwards if exceeding the limit is an error, because `readNBytes` stops silently at `len`.
- How does the character side of this contract compare, in java.io.Reader?It has the same shape. `Reader.read()` returns an `int` from 0 to 65535, or -1 at end of stream. `Reader.read(char[])` blocks until some input is available, then stores at least one character unless the buffer is empty or the stream has ended. So a character read can be short too, and its count is in `char` values, not bytes.
A buffer read is like asking a courier for up to eight parcels. He hands over whatever has arrived, at least one unless the depot has closed for good, and you go back for the rest. Waiting for all eight is a different request, which is what readNBytes makes.
- read() yields a byte, so storing the result in a byte before checking for -1 is safe.
- read(byte[]) always fills the whole buffer unless the stream has ended.
- available() returning 0 means the stream has reached its end.
- available() gives the stream's total size, so it can size the buffer for the whole read.
- readAllBytes() and transferTo() close the stream once they reach the end.
- Interrupting the thread reliably frees a call blocked in readAllBytes() or transferTo().
- InputStream
- Java 1.0
- InputStream.readAllBytes
- Java 9
- InputStream.transferTo
- Java 9
- InputStream.readNBytes(byte[], int, int)
- Java 9
- InputStream.readNBytes(int)
- Java 11
Assumes Java 27; readAllBytes and transferTo date from Java 9, and InputStream's source is identical at Java 25.
context
- InputStream (Java SE 27 & JDK 27)docs.oracle.com
- ByteArrayInputStream (Java SE 27 & JDK 27)docs.oracle.com