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

public class HttpRequest {

    private final String url;
    private final String method;
    private final int timeoutSeconds;

    // Private constructor forces callers to use the Builder
    private HttpRequest(Builder builder) {
        this.url = builder.url;
        this.method = builder.method;
        this.timeoutSeconds = builder.timeoutSeconds;
    }

    public String getUrl()           { return url; }
    public String getMethod()        { return method; }
    public int    getTimeoutSeconds(){ return timeoutSeconds; }

    @Override
    public String toString() {
        return method + " " + url + " (timeout=" + timeoutSeconds + "s)";
    }

    // Static nested class — belongs to HttpRequest conceptually,
    // but needs NO access to any HttpRequest instance while building.
    public static class Builder {

        private String url    = "";
        private String method = "GET";     // sensible default
        private int    timeoutSeconds = 30; // sensible default

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

        public Builder method(String method) {
            this.method = method;
            return this;
        }

        public Builder timeoutSeconds(int seconds) {
            this.timeoutSeconds = seconds;
            return this;
        }

        // Creates the outer-class instance using 'this' Builder
        public HttpRequest build() {
            if (url.isBlank()) {
                throw new IllegalStateException("URL must not be blank");
            }
            return new HttpRequest(this); // passes itself to the private constructor
        }
    }

    public static void main(String[] args) {
        // No HttpRequest instance needed to create a Builder
        HttpRequest request = new HttpRequest.Builder()
                .url("https://api.thecodeforge.io/articles")
                .method("POST")
                .timeoutSeconds(10)
                .build();

        System.out.println(request);
    }
}

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

// A simple inclusive integer range that can be iterated
public class NumberRange implements Iterable<Integer> {

    private final int start;
    private final int end;

    public NumberRange(int start, int end) {
        if (start > end) {
            throw new IllegalArgumentException("start must be <= end");
        }
        this.start = start;
        this.end   = end;
    }

    @Override
    public Iterator<Integer> iterator() {
        // Returns a new RangeIterator tied to THIS NumberRange instance
        return new RangeIterator();
    }

    // Non-static inner class — it needs to read 'start' and 'end'
    // from the enclosing NumberRange instance. Making this static
    // would require passing start/end explicitly; inner class reads them for free.
    private class RangeIterator implements Iterator<Integer> {

        private int current = start; // directly reads outer instance field

        @Override
        public boolean hasNext() {
            return current <= end;  // reads outer instance field 'end'
        }

        @Override
        public Integer next() {
            if (!hasNext()) {
                throw new NoSuchElementException(
                    "No more values in range [" + start + ", " + end + "]"
                );
            }
            return current++;
        }
    }

    public static void main(String[] args) {
        NumberRange range = new NumberRange(1, 5);

        // Enhanced for-loop uses the iterator() method under the hood
        for (int number : range) {
            System.out.print(number + " ");
        }
        System.out.println();

        // Each call to iterator() creates a fresh, independent RangeIterator
        Iterator<Integer> it1 = range.iterator();
        Iterator<Integer> it2 = range.iterator();
        System.out.println("it1 first: " + it1.next()); // advances it1 only
        System.out.println("it2 first: " + it2.next()); // it2 still starts at 1
    }
}

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

public class SortingDemo {

    public static void main(String[] args) {

        List<String> cities = Arrays.asList(
            "Tokyo", "Berlin", "São Paulo", "Lagos", "Melbourne"
        );

        // ── LOCAL CLASS EXAMPLE ──────────────────────────────────────────
        // Suppose we want a Comparator that sorts by string length first,
        // then alphabetically. This logic is only needed in this method.
        final boolean ascending = true; // effectively final — captured below

        class LengthThenAlphaComparator implements Comparator<String> {

            @Override
            public int compare(String a, String b) {
                // Uses 'ascending' from the enclosing method scope
                int lengthDiff = Integer.compare(a.length(), b.length());
                if (lengthDiff != 0) {
                    return ascending ? lengthDiff : -lengthDiff;
                }
                return a.compareTo(b); // alphabetical tiebreak
            }
        }

        List<String> citiesCopy = new java.util.ArrayList<>(cities);
        citiesCopy.sort(new LengthThenAlphaComparator());
        System.out.println("Local class sort:     " + citiesCopy);

        // ── ANONYMOUS CLASS EXAMPLE ──────────────────────────────────────
        // Same comparator, but written inline as an anonymous class.
        // Useful when you won't reuse the name anywhere in this method.
        citiesCopy = new java.util.ArrayList<>(cities);
        citiesCopy.sort(new Comparator<String>() {
            @Override
            public int compare(String a, String b) {
                // Sorts purely by length descending — longest city name first
                return Integer.compare(b.length(), a.length());
            }
        });
        System.out.println("Anonymous class sort: " + citiesCopy);

        // ── LAMBDA (for contrast) ────────────────────────────────────────
        // A lambda replaces a single-abstract-method anonymous class.
        // Clean, concise. Use lambdas over anonymous classes for SAM interfaces.
        citiesCopy = new java.util.ArrayList<>(cities);
        citiesCopy.sort((a, b) -> a.compareTo(b));
        System.out.println("Lambda sort:          " + citiesCopy);
    }
}

import java.time.LocalDateTime;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;

// Demonstrates static nested class (Transaction) and
// non-static inner class (TransactionView) in one cohesive example
public class BankAccount {

    private final String accountNumber;
    private double balancePence; // stored in pence to avoid floating-point drift
    private final List<Transaction> history = new ArrayList<>();

    public BankAccount(String accountNumber, double openingBalancePounds) {
        this.accountNumber = accountNumber;
        this.balancePence  = Math.round(openingBalancePounds * 100);
    }

    public void deposit(double amountPounds) {
        long amountPence = Math.round(amountPounds * 100);
        balancePence += amountPence;
        // Transaction is a value object — no need to know which account created it
        history.add(new Transaction("DEPOSIT", amountPence, balancePence));
    }

    public void withdraw(double amountPounds) {
        long amountPence = Math.round(amountPounds * 100);
        if (amountPence > balancePence) {
            throw new IllegalStateException("Insufficient funds");
        }
        balancePence -= amountPence;
        history.add(new Transaction("WITHDRAWAL", amountPence, balancePence));
    }

    // Returns a read-only view tied to THIS account instance
    public TransactionView getView() {
        return new TransactionView(); // creates inner class instance via outer instance
    }

    // ── STATIC NESTED CLASS ─────────────────────────────────────────────────
    // Transaction is a pure value/data object. It records what happened.
    // It doesn't need to call any method on BankAccount, so it's static.
    public static class Transaction {
        private final String          type;
        private final long            amountPence;
        private final long            balanceAfterPence;
        private final LocalDateTime   timestamp;

        private Transaction(String type, long amountPence, long balanceAfterPence) {
            this.type              = type;
            this.amountPence       = amountPence;
            this.balanceAfterPence = balanceAfterPence;
            this.timestamp         = LocalDateTime.now();
        }

        @Override
        public String toString() {
            return String.format("%-12s £%6.2f  (balance: £%.2f)",
                type, amountPence / 100.0, balanceAfterPence / 100.0);
        }
    }

    // ── NON-STATIC INNER CLASS ──────────────────────────────────────────────
    // TransactionView is a *view of this specific account*.
    // It reads 'accountNumber', 'balancePence', and 'history' from the
    // enclosing BankAccount instance — it genuinely needs the outer instance.
    public class TransactionView {

        public void printStatement() {
            // Directly accesses outer instance's private fields — no getters needed
            System.out.println("Account: " + accountNumber);
            System.out.printf ("Balance: £%.2f%n", balancePence / 100.0);
            System.out.println("──────────────────────────────────────────");
            List<Transaction> snapshot = Collections.unmodifiableList(history);
            if (snapshot.isEmpty()) {
                System.out.println("No transactions yet.");
            } else {
                snapshot.forEach(System.out::println);
            }
        }
    }

    public static void main(String[] args) {
        BankAccount account = new BankAccount("GB29-NWBK-1234", 500.00);
        account.deposit(150.75);
        account.withdraw(42.00);
        account.deposit(10.00);

        // Getting a view — inner class instance is created through the outer instance
        TransactionView view = account.getView();
        view.printStatement();

        // A Transaction can be used standalone — it's a static nested class
        BankAccount.Transaction sampleTx =
            new BankAccount.Transaction("REFUND", 500, 65075); // only possible if public
        // Note: constructor is private here, so this line would not compile.
        // Shown to illustrate the syntax for public static nested classes.
    }
}