I/O Basics

// ── The four abstract base classes ───────────────────────────────────
// Byte input:
InputStream  byteIn;   // abstract: read(), read(byte[]), read(byte[], off, len), close()

// Byte output:
OutputStream byteOut;  // abstract: write(int), write(byte[]), write(byte[], off, len), flush(), close()

// Character input:
Reader       charIn;   // abstract: read(), read(char[]), read(char[], off, len), close()

// Character output:
Writer       charOut;  // abstract: write(int), write(char[]), write(String), flush(), close()

// ── Source → Processor → Consumer chain ──────────────────────────────

// Simple: read a file byte by byte (unbuffered — very slow)
try (InputStream raw = new FileInputStream("data.bin")) {
    int b;
    while ((b = raw.read()) != -1) {
        // b is a byte value 0–255; -1 signals end of stream
        System.out.print(b + " ");
    }
}

// Better: file → buffer → consumer (buffered — efficient)
try (InputStream buffered = new BufferedInputStream(new FileInputStream("data.bin"))) {
    byte[] chunk = new byte[4096];
    int bytesRead;
    while ((bytesRead = buffered.read(chunk)) != -1) {
        process(chunk, 0, bytesRead);
    }
}

// Layered: file → buffer → data types → application
try (DataInputStream dis = new DataInputStream(
        new BufferedInputStream(new FileInputStream("data.bin")))) {
    int version = dis.readInt();       // reads 4 bytes as big-endian int
    double value = dis.readDouble();   // reads 8 bytes as IEEE 754 double
    String name  = dis.readUTF();      // reads length-prefixed UTF-8 string
    System.out.printf("v=%d val=%.2f name=%s%n", version, value, name);
}

// ── Byte stream vs character stream — always use the right one ────────
// WRONG: reading UTF-8 text with a byte stream
try (InputStream is = new FileInputStream("text.txt")) {
    int b;
    StringBuilder sb = new StringBuilder();
    while ((b = is.read()) != -1) {
        sb.append((char) b);   // WRONG: casts raw byte to char — breaks on UTF-8 multi-byte
    }
    System.out.println(sb);   // garbled for any non-ASCII characters
}

// CORRECT: reading UTF-8 text with a Reader
try (Reader reader = new InputStreamReader(new FileInputStream("text.txt"),
        StandardCharsets.UTF_8)) {
    int c;
    StringBuilder sb = new StringBuilder();
    while ((c = reader.read()) != -1) {
        sb.append((char) c);   // c is a Java char — correctly decoded from UTF-8
    }
    System.out.println(sb);
}

// BEST: buffered reader with charset
try (BufferedReader br = new BufferedReader(
        new InputStreamReader(new FileInputStream("text.txt"), StandardCharsets.UTF_8))) {
    String line;
    while ((line = br.readLine()) != null) {
        System.out.println(line);
    }
}

// ── The read() contract — the most important detail in all of Java I/O
// read() returns an int (not a byte) to allow -1 as the end-of-stream sentinel.
// If read() returned a byte, -1 could be confused with the valid byte value 0xFF.
// WRONG — misses last byte when its value is 0xFF:
// byte b = (byte) stream.read();   // WRONG: 0xFF becomes -1 (byte), indistinguishable from EOF

// CORRECT:
int value = stream.read();
if (value == -1) {
    // end of stream
} else {
    byte b = (byte) value;   // safe cast — value is in range [0, 255]
}

// ── Buffering performance comparison ─────────────────────────────────
// Unbuffered write — one system call per byte (catastrophically slow):
long start = System.nanoTime();
try (FileOutputStream fos = new FileOutputStream("unbuffered.bin")) {
    for (int i = 0; i < 1_000_000; i++) {
        fos.write(i & 0xFF);   // 1,000,000 individual write() system calls
    }
}
System.out.printf("Unbuffered: %.2f ms%n", (System.nanoTime() - start) / 1e6);
// Typical: 2000–10000ms — completely unacceptable

// Buffered write — one system call per 8KB (correct):
start = System.nanoTime();
try (BufferedOutputStream bos = new BufferedOutputStream(
        new FileOutputStream("buffered.bin"))) {
    for (int i = 0; i < 1_000_000; i++) {
        bos.write(i & 0xFF);   // writes to 8KB in-memory buffer
    }
    // bos.flush() called by close() via try-with-resources
}
System.out.printf("Buffered: %.2f ms%n", (System.nanoTime() - start) / 1e6);
// Typical: 3–10ms — 100–1000x faster

// Chunked write — explicitly writing arrays (often fastest):
start = System.nanoTime();
try (FileOutputStream fos = new FileOutputStream("chunked.bin")) {
    byte[] chunk = new byte[65536];   // 64KB chunks
    for (int offset = 0; offset < 1_000_000; offset += chunk.length) {
        int len = Math.min(chunk.length, 1_000_000 - offset);
        fos.write(chunk, 0, len);
    }
}
System.out.printf("Chunked: %.2f ms%n", (System.nanoTime() - start) / 1e6);
// Typical: 2–8ms — comparable to buffered

// ── Flush semantics — data loss without flush/close ──────────────────
// DANGEROUS: data loss if JVM crashes before close()
BufferedWriter writer = new BufferedWriter(new FileWriter("output.txt"));
writer.write("Important data");
// If program crashes here — "Important data" is in the buffer, NOT on disk
// JVM termination without close() loses buffered data permanently

// SAFE: try-with-resources always calls close() → close() calls flush()
try (BufferedWriter safeWriter = new BufferedWriter(new FileWriter("output.txt"))) {
    safeWriter.write("Important data");
    // Even if exception thrown, try-with-resources calls close() → flush() → data saved
}

// EXPLICIT FLUSH: use when you need confirmation of write before close()
try (BufferedOutputStream bos = new BufferedOutputStream(
        new FileOutputStream("critical.bin"))) {
    bos.write(criticalData);
    bos.flush();   // ensures data is written to OS (not necessarily to disk — use fsync for that)
    verifyDataWasWritten();   // can now check for partial-write errors
}

// ── Custom buffer size — when 8KB default isn't optimal ──────────────
// Larger buffer for bulk I/O operations:
try (BufferedInputStream bis = new BufferedInputStream(
        new FileInputStream("large-file.bin"), 65536)) {   // 64KB buffer
    // Each fill of the buffer reads 64KB in one system call
    byte[] buf = new byte[65536];
    int n;
    while ((n = bis.read(buf)) != -1) { process(buf, n); }
}

// ── Decorator chain — always close the OUTERMOST wrapper ─────────────
// CORRECT: close the outermost — propagates through the chain:
FileInputStream fis = new FileInputStream("file.bin");
BufferedInputStream bis = new BufferedInputStream(fis);
DataInputStream dis = new DataInputStream(bis);
dis.close();   // closes DataInputStream → BufferedInputStream → FileInputStream

// try-with-resources handles this correctly:
try (DataInputStream dis2 = new DataInputStream(
        new BufferedInputStream(new FileInputStream("file.bin")))) {
    int version = dis2.readInt();
    // dis2.close() called: closes DataInputStream → BufferedInputStream → FileInputStream
}

// WRONG: closing inner stream leaves outer wrappers in inconsistent state:
// fis.close();   // closes file descriptor, but bis and dis still exist
// bis.read();    // IOException: stream closed (or undefined behavior)

// ── System standard streams ───────────────────────────────────────────
System.out.println("Standard output");      // PrintStream — no IOException
System.err.println("Standard error");       // PrintStream — writes to stderr
System.out.flush();                         // explicit flush for time-sensitive output

// Reading from System.in — wrap for usability:
try (BufferedReader stdin = new BufferedReader(
        new InputStreamReader(System.in, StandardCharsets.UTF_8))) {
    System.out.print("Enter name: ");
    String line = stdin.readLine();
    System.out.println("Hello, " + line);
}

// Scanner is a higher-level wrapper around System.in:
Scanner scanner = new Scanner(System.in, StandardCharsets.UTF_8);
String input = scanner.nextLine();
scanner.close();   // but closing Scanner also closes System.in — use with care in tests

// ── Redirecting standard streams for testing ──────────────────────────
PrintStream originalOut = System.out;     // save original
ByteArrayOutputStream captured = new ByteArrayOutputStream();
System.setOut(new PrintStream(captured, true, StandardCharsets.UTF_8));

try {
    System.out.println("This is captured");
    System.out.printf("Value: %d%n", 42);
} finally {
    System.setOut(originalOut);           // ALWAYS restore
}

String output = captured.toString(StandardCharsets.UTF_8);
System.out.println("Captured: " + output.strip());
// Captured: This is captured
//           Value: 42

// ── PrintStream vs PrintWriter — suppress vs propagate ────────────────
// PrintStream: suppresses IOException, sets error flag
PrintStream ps = new PrintStream(new FileOutputStream("out.txt"), true, StandardCharsets.UTF_8);
ps.println("hello");
if (ps.checkError()) {
    System.err.println("Write failed — PrintStream swallowed the exception!");
}

// PrintWriter: proper exception propagation (when constructed with autoFlush=false)
try (PrintWriter pw = new PrintWriter(new BufferedWriter(
        new FileWriter("out.txt", StandardCharsets.UTF_8)))) {
    pw.println("hello");
    pw.println("world");
    if (pw.checkError()) throw new IOException("PrintWriter write failed");
}

// ── try-with-resources — the ONLY correct way to manage I/O resources ─
// WRONG: manual try/finally — broken when close() throws
InputStream is = null;
try {
    is = new FileInputStream("file.txt");
    process(is);
} finally {
    if (is != null) {
        try { is.close(); }
        catch (IOException e) { /* second exception swallows first — data lost */ }
    }
}

// CORRECT: try-with-resources — handles suppressed exceptions properly
try (InputStream is2 = new FileInputStream("file.txt")) {
    process(is2);
}   // is2.close() always called, exceptions properly suppressed

// Multiple resources — closed in reverse declaration order:
try (FileInputStream fis  = new FileInputStream("input.txt");
     FileOutputStream fos = new FileOutputStream("output.txt");
     DataInputStream  dis = new DataInputStream(fis)) {
    // Closed order on exit: dis → fos → fis
    int n = dis.readInt();
    fos.write(n & 0xFF);
}

// ── Suppressed exceptions — what try-with-resources does internally ───
// If process(is) throws exception A, and is.close() throws exception B:
// A is the primary exception (from the body)
// B is suppressed and attached to A
try (InputStream failStream = new InputStream() {
    @Override public int read() throws IOException { throw new IOException("Read failed"); }
    @Override public void close() throws IOException { throw new IOException("Close failed"); }
}) {
    failStream.read();
} catch (IOException e) {
    System.out.println("Primary:   " + e.getMessage());           // Read failed
    System.out.println("Suppressed: " + e.getSuppressed()[0].getMessage()); // Close failed
}