Java Data Streams
What Data Streams Do
Byte streams move raw bytes, and character streams move text. But programs work with numbers, booleans and strings. Data streams convert Java's primitive types to and from a fixed binary representation:
| Class | Wraps | Purpose |
|---|---|---|
DataOutputStream | An OutputStream | Writes int, long, double, boolean, String, ... as bytes |
DataInputStream | An InputStream | Reads them back |
out.writeInt(1001); // always exactly 4 bytes
int id = in.readInt(); // reads exactly 4 bytes back into an int
Why use a binary format instead of text?
- Compactness: an
intis always 4 bytes, whereas"1794635670"as text is 10 bytes plus a separator. - Speed: no parsing or formatting of text — the bytes are converted directly.
- Exactness: a
doubleis written as its exact 8-byte IEEE 754 representation, so it's read back bit-for-bit identical, with no rounding through decimal text. - Fixed structure: each value has a known size, which makes formats simple to read with fixed offsets.
The trade-off is that binary data isn't human-readable, and the reader must know exactly what was written and in which order. Data streams are used for custom file formats, caches, network protocols, and inside the JDK itself (the .class file format and Java serialization are built on them).
Writing and Reading Primitive Values
import java.io.*;
import java.util.HexFormat;
public class D1 {
public static void main(String[] args) throws IOException {
ByteArrayOutputStream bytes = new ByteArrayOutputStream();
try (DataOutputStream out = new DataOutputStream(bytes)) {
out.writeInt(1001);
out.writeDouble(4999.5);
out.writeBoolean(true);
out.writeUTF("Gel pen ₹");
out.writeLong(1_794_635_670_123L);
System.out.println("bytes written: " + out.size());
}
byte[] data = bytes.toByteArray();
System.out.println("hex: " + HexFormat.ofDelimiter(" ").formatHex(data, 0, 16) + " ...");
try (DataInputStream in = new DataInputStream(new ByteArrayInputStream(data))) {
System.out.println("int: " + in.readInt());
System.out.println("double: " + in.readDouble());
System.out.println("boolean: " + in.readBoolean());
System.out.println("UTF: " + in.readUTF());
System.out.println("long: " + in.readLong());
try {
in.readInt();
} catch (EOFException e) {
System.out.println("readInt at the end: EOFException");
}
}
try (DataInputStream in = new DataInputStream(new ByteArrayInputStream(data))) {
System.out.println("wrong order, readDouble first: " + in.readDouble());
}
}
}
Output:
bytes written: 34
hex: 00 00 03 e9 40 b3 87 80 00 00 00 00 01 00 0b 47 ...
int: 1001
double: 4999.5
boolean: true
UTF: Gel pen ₹
long: 1794635670123
readInt at the end: EOFException
wrong order, readDouble first: 2.1246540986986E-311
The binary layout
| Method pair | Bytes | Format |
|---|---|---|
writeBoolean / readBoolean | 1 | 1 for true, 0 for false |
writeByte / readByte, readUnsignedByte | 1 | |
writeShort / readShort, readUnsignedShort | 2 | Big-endian |
writeChar / readChar | 2 | UTF-16 code unit |
writeInt / readInt | 4 | Big-endian two's complement |
writeLong / readLong | 8 | Big-endian |
writeFloat / readFloat | 4 | IEEE 754 |
writeDouble / readDouble | 8 | IEEE 754 |
writeUTF / readUTF | 2 + length | 2-byte length, then the string in modified UTF-8 |
The hex dump shows this directly: 00 00 03 e9 is 1001 as a 4-byte big-endian int; the next 8 bytes are the double 4999.5; 01 is true; 00 0b is the string's length (11 bytes: 8 ASCII characters plus 3 bytes for ₹), followed by its bytes (47 is G). The total is 4 + 8 + 1 + 13 + 8 = 34 bytes, which size() reports.
All multi-byte values are big-endian (most significant byte first), also called network byte order. That makes the format identical on every platform, but different from little-endian formats such as BMP or ZIP headers (see the NIO Basics lesson for ByteBuffer with a configurable byte order).
Rules that follow from the format
- Read in exactly the order you wrote. The bytes carry no type information. Reading the data with
readDouble()first interprets theintand the first half of thedoubleas one double, producing the meaningless2.12E-311— with no error. A binary format is a contract between the writer and the reader. - End of data is reported with
EOFException. Unlikeread(), which returns-1, thereadXxxmethods need a fixed number of bytes; if the stream ends before they get them, they throwEOFException(a subclass ofIOException). That's also what you get from a truncated file. readFully(byte[])reads exactly the array's length or throwsEOFException, solving the partial-read problem ofInputStream.read(InputStream lesson).
writeUTF and its limits
writeUTF is convenient for short strings, but it has two quirks:
- The length prefix is 2 bytes, so the encoded string can't exceed 65,535 bytes; longer strings throw
UTFDataFormatException. - It uses modified UTF-8, which differs from standard UTF-8 for the
\u0000character and for characters outside the Basic Multilingual Plane (such as emoji). Other languages' UTF-8 decoders may not read it correctly.
For long text, or for formats read by non-Java programs, write the string's standard UTF-8 bytes with your own length prefix instead — as the last example in this lesson does.
Practical Example: A Binary Sensor Data File
A monitoring system records temperature readings from cold-storage rooms every minute. A compact binary file stores them efficiently and can be read back quickly and exactly. A well-designed binary format starts with a header that identifies the file and its version, so the reader can reject wrong or incompatible files instead of producing garbage.
import java.io.*;
import java.nio.file.*;
import java.time.Instant;
import java.util.*;
public class Sensor {
static final int MAGIC = 0x534E5344; // "SNSD"
static final short VERSION = 1;
record Reading(Instant time, String sensorId, double celsius, boolean alarm) { }
static void save(Path file, List<Reading> readings) throws IOException {
try (DataOutputStream out = new DataOutputStream(new BufferedOutputStream(Files.newOutputStream(file)))) {
out.writeInt(MAGIC);
out.writeShort(VERSION);
out.writeInt(readings.size());
for (Reading r : readings) {
out.writeLong(r.time().toEpochMilli());
out.writeUTF(r.sensorId());
out.writeDouble(r.celsius());
out.writeBoolean(r.alarm());
}
}
}
static List<Reading> load(Path file) throws IOException {
try (DataInputStream in = new DataInputStream(new BufferedInputStream(Files.newInputStream(file)))) {
if (in.readInt() != MAGIC) throw new IOException(file + " is not a sensor data file");
short version = in.readShort();
if (version != VERSION) throw new IOException("unsupported version " + version);
int count = in.readInt();
if (count < 0 || count > 10_000_000) throw new IOException("corrupt record count " + count);
List<Reading> result = new ArrayList<>(count);
for (int i = 0; i < count; i++) {
result.add(new Reading(Instant.ofEpochMilli(in.readLong()), in.readUTF(), in.readDouble(), in.readBoolean()));
}
return result;
}
}
public static void main(String[] args) throws IOException {
Instant t0 = Instant.parse("2026-11-15T06:00:00Z");
List<Reading> readings = new ArrayList<>();
for (int i = 0; i < 1000; i++) {
double c = 21.5 + (i % 40) * 0.25;
readings.add(new Reading(t0.plusSeconds(60L * i), "cold-room-" + (i % 3 + 1), c, c > 30));
}
Path bin = Path.of("readings.bin");
save(bin, readings);
StringBuilder csv = new StringBuilder("time,sensor,celsius,alarm\n");
for (Reading r : readings) csv.append(r.time()).append(',').append(r.sensorId()).append(',').append(r.celsius()).append(',').append(r.alarm()).append('\n');
Files.writeString(Path.of("readings.csv"), csv);
System.out.println("binary: " + Files.size(bin) + " bytes, CSV: " + Files.size(Path.of("readings.csv")) + " bytes");
List<Reading> back = load(bin);
System.out.println("loaded " + back.size() + " readings, identical: " + back.equals(readings));
System.out.println("last: " + back.get(back.size() - 1));
System.out.println("alarms: " + back.stream().filter(Reading::alarm).count());
Files.writeString(Path.of("notes.txt"), "not sensor data");
try {
load(Path.of("notes.txt"));
} catch (IOException e) {
System.out.println("load notes.txt: " + e.getMessage());
}
byte[] all = Files.readAllBytes(bin);
Files.write(Path.of("truncated.bin"), Arrays.copyOf(all, all.length - 10));
try {
load(Path.of("truncated.bin"));
} catch (EOFException e) {
System.out.println("load truncated.bin: EOFException (file ended early)");
}
}
}
Output:
binary: 30010 bytes, CSV: 44401 bytes
loaded 1000 readings, identical: true
last: Reading[time=2026-11-15T22:39:00Z, sensorId=cold-room-1, celsius=31.25, alarm=true]
alarms: 125
load notes.txt: notes.txt is not a sensor data file
load truncated.bin: EOFException (file ended early)
How the format works:
- Header (10 bytes). A 4-byte magic number (
0x534E5344, the ASCII lettersSNSD), a 2-byte version, and a 4-byte record count. Magic numbers are how real formats identify themselves — PNG files start with89 50 4E 47, Java class files withCA FE BA BE. - Records (30 bytes each). A timestamp as epoch milliseconds (8 bytes), the sensor ID with
writeUTF(2 + 11 bytes), the temperature (8) and the alarm flag (1). With 1,000 readings, the file is exactly 10 + 30,000 = 30,010 bytes, about two-thirds the size of the equivalent CSV. - Buffering. Every
writeXxxandreadXxxcall writes or reads a few bytes, so the file streams are wrapped inBufferedOutputStreamandBufferedInputStream. Without them, every small value would be a separate system call (Buffered Streams lesson). - Loading reverses the writing order exactly. The
Readingconstructor arguments are evaluated left to right, matching the order in whichsavewrote the fields. Because doubles are stored bit-for-bit,back.equals(readings)istrue. - Validation before trust. The loader checks the magic number (rejecting
notes.txt), the version (so a future version 2 file isn't misread), and the record count (a corrupted count could otherwise makenew ArrayList<>(count)try to allocate gigabytes). A file cut short producesEOFExceptioninstead of silently returning partial data.
When the format evolves — for example, a humidity field is added — increase VERSION and let the loader handle both versions. Without the version field, old and new files would be indistinguishable.
Practical Example: Length-Prefixed Messages
Over a TCP connection, data arrives as a continuous stream of bytes with no message boundaries: two messages sent separately can arrive together, and one message can arrive in pieces. A common solution is framing: send each message's length first, then its bytes. The receiver reads the length, then reads exactly that many bytes.
import java.io.*;
import java.nio.charset.StandardCharsets;
import java.util.*;
public class Frames {
static void sendMessage(DataOutputStream out, String json) throws IOException {
byte[] payload = json.getBytes(StandardCharsets.UTF_8);
out.writeInt(payload.length);
out.write(payload);
out.flush();
}
static Optional<String> receiveMessage(DataInputStream in) throws IOException {
int length;
try {
length = in.readInt();
} catch (EOFException e) {
return Optional.empty();
}
if (length < 0 || length > 1_000_000) throw new IOException("invalid frame length " + length);
byte[] payload = new byte[length];
in.readFully(payload);
return Optional.of(new String(payload, StandardCharsets.UTF_8));
}
public static void main(String[] args) throws IOException {
ByteArrayOutputStream wire = new ByteArrayOutputStream();
DataOutputStream out = new DataOutputStream(wire);
sendMessage(out, "{\"type\":\"order\",\"id\":1001}");
sendMessage(out, "{\"type\":\"note\",\"text\":\"line one\\nline two, ₹500\"}");
sendMessage(out, "{}");
System.out.println("bytes on the wire: " + wire.size());
DataInputStream in = new DataInputStream(new ByteArrayInputStream(wire.toByteArray()));
Optional<String> msg;
while ((msg = receiveMessage(in)).isPresent()) {
System.out.println("received: " + msg.get());
}
System.out.println("connection closed cleanly");
}
}
Output:
bytes on the wire: 91
received: {"type":"order","id":1001}
received: {"type":"note","text":"line one\nline two, ₹500"}
received: {}
connection closed cleanly
Step by step:
- Sending. The message is converted to standard UTF-8 bytes, then the byte count is written as a 4-byte
int, followed by the bytes themselves.flush()makes sure the message is sent immediately — important on a real socket, where the other side is waiting for it. - Receiving.
readInt()reads the length.readFully(payload)then reads exactly that many bytes, waiting for more data if the message arrives in pieces — the part a plainread(byte[])wouldn't guarantee. - Message content is unrestricted. The second message contains a newline, a comma and a multi-byte character; none of them confuse the framing, unlike line-based protocols where a newline inside a message would split it.
- Clean end versus truncation. An
EOFExceptionwhile reading the length means the other side closed the connection between messages — a normal end, reported as an emptyOptional. AnEOFExceptionfromreadFully(not caught here) would mean the connection broke in the middle of a message, which is a genuine error. - Never trust the length. A corrupted or malicious length such as 2,000,000,000 would make the receiver allocate a 2 GB array. Checking it against a maximum before allocating protects the server.
The ByteArrayOutputStream stands in for a network connection here. With a real socket, out would wrap socket.getOutputStream() and in would wrap socket.getInputStream() (both buffered) — the framing code stays the same. Many real protocols, including Kafka's, PostgreSQL's wire protocol and gRPC's message framing, use length-prefixed frames in this way.