Java Inner Classes Explained — Types, Use Cases and Hidden Pitfalls

import java.util.Iterator;
import java.util.NoSuchElementException;

/**
 * A minimal collection that holds a fixed list of words.
 * Its private Iterator is implemented as a non-static inner class
 * because the iterator needs direct access to the private 'words' array.
 */
public class WordCollection implements Iterable<String> {

    // Private backing array — the inner class can read this directly
    private final String[] words;

    public WordCollection(String... words) {
        this.words = words;
    }

    // The factory method returns our custom iterator
    @Override
    public Iterator<String> iterator() {
        return new WordIterator(); // creates an inner instance tied to THIS WordCollection
    }

    // ── Non-static inner class ─────────────────────────────────────────────────
    // No 'static' keyword — so every WordIterator instance carries a hidden
    // reference to the enclosing WordCollection instance that created it.
    private class WordIterator implements Iterator<String> {

        private int currentIndex = 0; // tracks our position in the outer 'words' array

        @Override
        public boolean hasNext() {
            // 'words' here refers to the OUTER class's private field — no getter needed
            return currentIndex < words.length;
        }

        @Override
        public String next() {
            if (!hasNext()) {
                throw new NoSuchElementException(
                    "No more words at index " + currentIndex
                );
            }
            return words[currentIndex++]; // read outer field, then advance index
        }
    }
    // ── End of inner class ────────────────────────────────────────────────────

    public static void main(String[] args) {
        WordCollection collection = new WordCollection("Forge", "Build", "Ship", "Repeat");

        // The enhanced for-loop calls collection.iterator() behind the scenes
        for (String word : collection) {
            System.out.println("Word: " + word);
        }
    }
}

/**
 * Pizza uses the Builder pattern implemented as a static nested class.
 * The Builder is nested for API clarity (Pizza.Builder), but it's static
 * because it constructs a NEW Pizza — it doesn't operate on an existing one.
 */
public class Pizza {

    private final String crustType;
    private final String sauce;
    private final boolean hasExtraCheese;
    private final boolean hasMushroooms;

    // Private constructor — callers MUST go through the Builder
    private Pizza(Builder builder) {
        this.crustType      = builder.crustType;
        this.sauce          = builder.sauce;
        this.hasExtraCheese = builder.hasExtraCheese;
        this.hasMushroooms  = builder.hasMushroooms;
    }

    @Override
    public String toString() {
        return String.format(
            "Pizza{crust='%s', sauce='%s', extraCheese=%b, mushrooms=%b}",
            crustType, sauce, hasExtraCheese, hasMushroooms
        );
    }

    // ── Static nested class ───────────────────────────────────────────────────
    // 'static' means no hidden reference to a Pizza instance.
    // We can create a Builder without any existing Pizza object.
    public static class Builder {

        // Required parameter — set in constructor to enforce it
        private final String crustType;

        // Optional parameters — sensible defaults
        private String  sauce           = "tomato";
        private boolean hasExtraCheese  = false;
        private boolean hasMushroooms   = false;

        public Builder(String crustType) {
            this.crustType = crustType;
        }

        public Builder sauce(String sauce) {
            this.sauce = sauce;
            return this; // enables method chaining
        }

        public Builder extraCheese() {
            this.hasExtraCheese = true;
            return this;
        }

        public Builder mushrooms() {
            this.hasMushroooms = true;
            return this;
        }

        // The terminal operation — hands control back to the outer class constructor
        public Pizza build() {
            return new Pizza(this);
        }
    }
    // ── End of static nested class ────────────────────────────────────────────

    public static void main(String[] args) {
        // No existing Pizza needed to create a Builder — that's the static difference
        Pizza margherita = new Pizza.Builder("thin")
                .sauce("basil-tomato")
                .extraCheese()
                .build();

        Pizza mushPizza = new Pizza.Builder("thick")
                .mushrooms()
                .build();

        System.out.println(margherita);
        System.out.println(mushPizza);
    }
}

import java.util.Arrays;
import java.util.Comparator;
import java.util.List;

public class SortingDemo {

    public static void main(String[] args) {

        List<String> teamMembers = Arrays.asList(
            "Alice", "Bob", "Charlie", "Dan", "Eve"
        );

        // ── Anonymous inner class ─────────────────────────────────────────────
        // We implement Comparator<String> right here, inline, with no class name.
        // Use this when the logic is short and won't be reused anywhere else.
        Comparator<String> byLengthThenAlpha = new Comparator<String>() {

            @Override
            public int compare(String first, String second) {
                // Primary sort: shorter names come first
                int lengthDiff = Integer.compare(first.length(), second.length());
                if (lengthDiff != 0) {
                    return lengthDiff;
                }
                // Secondary sort: alphabetical for same-length names
                return first.compareTo(second); // falls back to natural order
            }

            // Anonymous classes CAN override additional methods — unlike lambdas.
            // This is a legitimate reason to still prefer anonymous classes
            // over lambdas even in modern Java.
            @Override
            public boolean equals(Object other) {
                return other instanceof Comparator
                    && other.getClass() == this.getClass();
            }
        };
        // ── End of anonymous inner class ─────────────────────────────────────

        teamMembers.sort(byLengthThenAlpha);
        System.out.println("Sorted by length then alpha:");
        teamMembers.forEach(name -> System.out.println("  " + name));

        // ── Local inner class (rare, shown for completeness) ──────────────────
        // Declared inside a method, visible only within this method block.
        class LengthPrinter {
            void print(String label, int length) {
                // 'teamMembers' from enclosing method is accessible because
                // it's effectively final (never reassigned after initialisation)
                System.out.printf("%s has %d characters%n", label, length);
            }
        }

        LengthPrinter printer = new LengthPrinter();
        printer.print(teamMembers.get(0), teamMembers.get(0).length());
    }
}

/**
 * This file demonstrates three common inner class mistakes side-by-side
 * with their correct counterparts. Run it to confirm the fixes work.
 */
public class InnerClassGotchas {

    private String status = "ACTIVE";

    // ── MISTAKE 1 FIX: Correct instantiation syntax ───────────────────────────
    // Wrong:  InnerHelper helper = new InnerHelper();  // compile error outside outer class
    // Right:  You need an outer instance first
    class InnerHelper {
        void describeStatus() {
            // MISTAKE 3 FIX: Use the qualified 'this' to get the OUTER instance
            // 'this' alone refers to the InnerHelper instance, NOT InnerClassGotchas
            String outerStatus = InnerClassGotchas.this.status; // outer 'this'
            System.out.println("Outer status via qualified this: " + outerStatus);

            // 'this' without qualification = the InnerHelper instance
            System.out.println("Inner class type: " + this.getClass().getSimpleName());
        }
    }

    // ── MISTAKE 2 FIX: Use static nested to avoid the hidden reference leak ───
    // Non-static (risky if passed to long-lived objects):
    //   class LeakyListener { ... }  // holds implicit ref to InnerClassGotchas instance
    //
    // Static (safe — no hidden outer reference):
    static class SafeListener {
        private final String listenerName;

        SafeListener(String listenerName) {
            this.listenerName = listenerName;
        }

        void onEvent(String eventType) {
            // Can't accidentally access outer instance fields here — compiler prevents it
            System.out.println(listenerName + " received event: " + eventType);
        }
    }

    public static void main(String[] args) {

        // MISTAKE 1 DEMO: Creating a non-static inner class from OUTSIDE the outer class
        InnerClassGotchas outerInstance = new InnerClassGotchas();

        // Correct syntax: outerInstance.new InnerClass()
        InnerClassGotchas.InnerHelper helper = outerInstance.new InnerHelper();
        helper.describeStatus();

        // Static nested class — created normally, no outer instance needed
        SafeListener listener = new SafeListener("ConnectionMonitor");
        listener.onEvent("DISCONNECT");
    }
}