{"title":"Inner Classes","description":"","content":"Java allows declaring a class inside another class. The class on the outside is the **enclosing** or **outer** class, and the one on the inside is a **nested** class. This is the standard way to keep a small helper type close to the code that uses it, hide it from the rest of the program, and (in one flavor) give it special access to the outer class's private fields.\n\nThis lesson covers three of the four kinds of nested classes: non-static inner classes, static nested classes, and local classes. The fourth kind, anonymous classes, has enough quirks of its own to deserve its own chapter, which comes next.\n\n---\n\n# Why Nest a Class At All\n\nMost classes live on their own at the top of a file. That's the default. Use a nested class when one of these is true:\n\n- A helper type is only meaningful inside its outer class. Putting it elsewhere would force callers to import a type they shouldn't even know exists.\n- A helper type needs to read the outer class's private state. With a top-level class, the outer class's API would have to widen just to share data.\n- A short, single-use type is needed for one method, and giving it its own file would feel heavy.\n\nTake a shopping cart. The cart itself is a public type the rest of the program uses. But the cart's iterator (the thing that walks through its items one at a time) is only useful from inside the cart. It needs to read the cart's internal array, and it has no use outside the cart. That's a case for a nested class.\n\nThe three flavors covered here differ in exactly one thing: their relationship to the outer class's instance. A static nested class has no relationship to it. A non-static inner class always belongs to one specific outer instance. A local class lives inside a method and disappears with it.\n\n\n```mermaid\nflowchart TD\n Outer[Outer class
ShoppingCart]:::cyan --> StaticNested[Static nested
Builder
no outer instance]:::orange\n Outer --> Inner[Non-static inner
CartIterator
holds outer instance]:::green\n Outer --> Local[Local class
defined in a method
visible in that method]:::teal\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n```\n\n\nThe diagram shows the three relationships at a glance. Each is covered below with code.\n\n---\n\n# Non-Static Inner Classes\n\nA non-static inner class (sometimes called a **member inner class**) is declared inside another class without the `static` keyword. Every instance of an inner class is tied to one specific instance of the outer class. That outer instance is called the **enclosing instance**.\n\nThe practical consequence is that the inner class can read and write the outer class's fields directly, even the private ones, because it's \"inside\" the outer class for visibility purposes.\n\nA small example before the full cart:\n\n\n```java\npublic class Store {\n private String storeName = \"AlgoMart\";\n\n public class Greeter {\n public void greet(String customer) {\n System.out.println(\"Hello \" + customer + \", welcome to \" + storeName + \"!\");\n }\n }\n\n public static void main(String[] args) {\n Store store = new Store();\n Store.Greeter greeter = store.new Greeter();\n greeter.greet(\"Alice\");\n }\n}\n```\n\n\nTwo things to point out. First, `Greeter` reaches into `storeName` directly, as if it were its own field. Second, creating a `Greeter` requires an existing `Store` instance: the unusual `store.new Greeter()` syntax. `new Greeter()` is not legal from outside `Store`, because a `Greeter` only makes sense in the context of a specific store.\n\nThe `store.new Greeter()` syntax reads as \"use this store, and from it, create a new Greeter\". It's the only place in Java where `new` appears after a dot like this. It looks odd because it is odd. Most inner-class instantiations happen from inside the outer class itself, where the shorter form `new Greeter()` works and implicitly uses `this` as the enclosing instance.\n\n### A Worked Example: ShoppingCart and Its Iterator\n\nThe point of a non-static inner class is to share state with the outer class. A custom iterator is the classic example. The code below defines a tiny interface for \"something you can ask for the next item\" and lets an inner `CartIterator` implement it against the cart's private storage.\n\n\n```java\npublic class ShoppingCart {\n // A tiny interface so we don't depend on java.util.Iterator yet.\n public interface Walker {\n boolean hasNext();\n String next();\n }\n\n private String[] items;\n private int size;\n\n public ShoppingCart(int capacity) {\n this.items = new String[capacity];\n this.size = 0;\n }\n\n public void add(String item) {\n items[size] = item;\n size++;\n }\n\n public Walker walker() {\n return new CartIterator();\n }\n\n // Non-static inner class. Sees the cart's private fields directly.\n private class CartIterator implements Walker {\n private int cursor = 0;\n\n @Override\n public boolean hasNext() {\n return cursor < size;\n }\n\n @Override\n public String next() {\n String value = items[cursor];\n cursor++;\n return value;\n }\n }\n\n public static void main(String[] args) {\n ShoppingCart cart = new ShoppingCart(5);\n cart.add(\"Wireless Mouse\");\n cart.add(\"USB Cable\");\n cart.add(\"Headphones\");\n\n Walker walker = cart.walker();\n while (walker.hasNext()) {\n System.out.println(walker.next());\n }\n }\n}\n```\n\n\nThe `CartIterator` reads `items` and `size` directly. Both are `private` on the outer class, but the inner class is part of the same class for visibility purposes, so the read is legal. From outside `ShoppingCart`, those fields are still invisible. The cart class as a whole still encapsulates them; the inner class is an additional viewpoint inside the same encapsulation boundary.\n\n`walker()` returns the iterator using the short form `new CartIterator()`. That's because it's running inside a `ShoppingCart` method, so `this` is the enclosing instance and Java fills it in automatically.\n\n### Accessing Outer Members With `OuterClass.this`\n\nSometimes the inner class declares a field or method with the same name as one in the outer class. Inside the inner class, the inner name wins, so a bare reference points to the inner version. To reach the outer one, use `OuterClass.this.fieldName`.\n\n\n```java\npublic class Catalog {\n private String name = \"Catalog\";\n\n public class Section {\n private String name = \"Section\";\n\n public void printNames() {\n System.out.println(\"Inner name: \" + name);\n System.out.println(\"Outer name: \" + Catalog.this.name);\n }\n }\n\n public static void main(String[] args) {\n Catalog catalog = new Catalog();\n Catalog.Section section = catalog.new Section();\n section.printNames();\n }\n}\n```\n\n\n`OuterClass.this` doesn't come up often. When it does, it's almost always to disambiguate a shadowed name. Most inner classes pick distinct field names and avoid the question entirely.\n\n### The Hidden Reference to the Outer Instance\n\nA non-static inner class always holds a reference to its enclosing instance. The compiler creates this reference automatically, but it's real, and it has two consequences.\n\nFirst, the inner instance can't outlive the outer instance without keeping the outer one alive. As long as something is holding the inner object, the garbage collector can't reclaim the outer object either, even if nothing else points to it.\n\n\n```java\npublic class CartHolder {\n private String[] items = new String[10_000];\n\n public class Snapshot {\n public int sizeAtSnapshot() {\n return items.length;\n }\n }\n\n public Snapshot snapshot() {\n return new Snapshot();\n }\n\n public static void main(String[] args) {\n CartHolder.Snapshot snapshot;\n\n {\n CartHolder cart = new CartHolder();\n snapshot = cart.snapshot();\n }\n\n // `cart` is out of lexical scope, but the snapshot still holds a hidden\n // reference to it, so the whole CartHolder (and its 10,000-slot array)\n // stays in memory as long as `snapshot` is reachable.\n System.out.println(\"Items array size: \" + snapshot.sizeAtSnapshot());\n }\n}\n```\n\n\nA non-static inner instance keeps its enclosing outer instance alive in memory for as long as the inner one is reachable. If the outer object is large (caches, big arrays, file handles), this can hold memory that would otherwise be freed. When the inner class doesn't need the outer instance, mark it `static`.\n\nSecond, before Java 16 the inner class couldn't have any static members of its own. The reasoning: every inner instance is tied to a separate enclosing instance, and a static field in the inner class would be ambiguous, shared across enclosing instances or per enclosing instance? Java 16 lifted this restriction so inner classes can now declare static members, but the underlying design point still holds: an inner class needing static state is often a signal it should be a static nested class instead.\n\n### What's Wrong With This Code?\n\n\n```java\npublic class Library {\n private String name = \"Central\";\n\n public class Section {\n public void print() {\n System.out.println(name);\n }\n }\n\n public static void main(String[] args) {\n Section section = new Section();\n section.print();\n }\n}\n```\n\n\n**Fix:**\n\n`Section` is a non-static inner class, so creating one requires an existing `Library` instance. The line `new Section()` has no outer instance to attach to and won't compile. The compiler reports something like `an enclosing instance that contains Library.Section is required`. The fix is to build the library first and then attach a section to it:\n\n\n```java\npublic class Library {\n private String name = \"Central\";\n\n public class Section {\n public void print() {\n System.out.println(name);\n }\n }\n\n public static void main(String[] args) {\n Library library = new Library();\n Library.Section section = library.new Section();\n section.print();\n }\n}\n```\n\n\nThe `library.new Section()` syntax is the way to say \"give me a Section attached to this Library\".\n\n---\n\n# Static Nested Classes\n\nA static nested class is declared inside another class with the `static` keyword. Despite living inside another class, it behaves almost exactly like a top-level class. It has no enclosing instance, doesn't hold a hidden reference to the outer object, and can be instantiated without one.\n\nThe reason to nest it at all is **namespacing**. Putting a `Builder` inside `ShoppingCart` makes its full name `ShoppingCart.Builder`, which signals what it's for. The builder doesn't need access to a particular cart instance because, by the time it runs, no cart exists yet. It's the thing that builds one.\n\n\n```java\npublic class CartBuilderDemo {\n public static class CartBuilder {\n private String customer;\n private int itemCount;\n private double total;\n\n public CartBuilder customer(String name) {\n this.customer = name;\n return this;\n }\n\n public CartBuilder items(int count) {\n this.itemCount = count;\n return this;\n }\n\n public CartBuilder total(double amount) {\n this.total = amount;\n return this;\n }\n\n public String build() {\n return \"Cart{customer=\" + customer + \", items=\" + itemCount + \", total=$\" + total + \"}\";\n }\n }\n\n public static void main(String[] args) {\n String description = new CartBuilder()\n .customer(\"Alice\")\n .items(3)\n .total(89.97)\n .build();\n\n System.out.println(description);\n }\n}\n```\n\n\n`new CartBuilder()` works directly. No `outer.new ...` is needed because the static nested class doesn't depend on an outer instance.\n\n### When to Pick Static Nested Over Non-Static Inner\n\nThe rule is short: if the nested class doesn't need to read or modify the outer instance's state, make it `static`.\n\n\n| Question | If yes... | If no... |\n| --- | --- | --- |\n| Does the helper need to access the outer instance's fields or instance methods? | Use a non-static inner class. | Use a static nested class. |\n| Could a meaningful instance of the helper exist before any outer instance exists? | Use a static nested class. | Use a non-static inner class. |\n| Is the helper conceptually about one specific outer instance? | Use a non-static inner class. | Use a static nested class. |\n\n\nDefaulting to `static` is the safer call. It uses less memory (no hidden outer reference) and it makes the dependency explicit: a static nested class that needs the outer instance has to receive it as a parameter, which forces the design decision to be explicit.\n\nIterators are non-static because they walk through one specific cart's items. Builders are static because the cart doesn't exist yet. Result classes (a return value bundling several fields) are usually static because they're data carriers. Listener classes that watch one specific object are usually non-static.\n\n### Accessing a Static Nested Class From Outside\n\nFrom outside the outer class, a static nested class is referenced with the dotted name `Outer.Inner`. From inside the outer class, the short name `Inner` works.\n\n\n```java\npublic class OrderModule {\n public static class OrderResult {\n public final int orderId;\n public final double total;\n\n public OrderResult(int orderId, double total) {\n this.orderId = orderId;\n this.total = total;\n }\n }\n\n public static OrderResult placeOrder(int orderId, double total) {\n return new OrderResult(orderId, total);\n }\n\n public static void main(String[] args) {\n OrderModule.OrderResult result = OrderModule.placeOrder(1042, 89.97);\n System.out.println(\"Order \" + result.orderId + \" total $\" + result.total);\n }\n}\n```\n\n\n`OrderResult` doesn't care about any particular `OrderModule` instance. It's a small data carrier that the outer class hands back. Marking it `static` makes that explicit and avoids a hidden outer reference.\n\n### What's Wrong With This Code?\n\n\n```java\npublic class Catalog {\n private String name = \"Main Catalog\";\n\n public static class Filter {\n public void describe() {\n System.out.println(\"Filtering \" + name);\n }\n }\n}\n```\n\n\n**Fix:**\n\n`Filter` is a static nested class, so it has no enclosing instance. The reference to `name` (a non-static field of `Catalog`) won't compile. The compiler says: `non-static variable name cannot be referenced from a static context`. There are two ways out, depending on intent.\n\nIf `Filter` actually needs the catalog's name, pass it in:\n\n\n```java\npublic class Catalog {\n private String name = \"Main Catalog\";\n\n public static class Filter {\n private final String catalogName;\n\n public Filter(String catalogName) {\n this.catalogName = catalogName;\n }\n\n public void describe() {\n System.out.println(\"Filtering \" + catalogName);\n }\n }\n\n public static void main(String[] args) {\n Catalog catalog = new Catalog();\n Filter filter = new Filter(catalog.name);\n filter.describe();\n }\n}\n```\n\n\nIf `Filter` needs to track the live state of a specific `Catalog` (so updates to `name` show up), make it a non-static inner class instead.\n\n---\n\n# Local Classes\n\nA local class is declared inside a method, constructor, or block, not inside the class body itself. It's only visible from the moment of its declaration to the closing brace of the enclosing block. Outside that block, the class is invisible.\n\nLocal classes are useful when a method needs a small custom type for its own work, and nothing outside the method should be able to see or use it. They're rarer than the other two flavors, but in the right spot they remove clutter.\n\n\n```java\npublic class OrderReceipt {\n public static String format(double subtotal, double taxRate, int itemCount) {\n // Local class: a tiny formatter used only by this method.\n class PriceFormatter {\n String currency(double amount) {\n return \"$\" + Math.round(amount * 100) / 100.0;\n }\n\n String line(String label, double amount) {\n return label + \": \" + currency(amount);\n }\n }\n\n PriceFormatter formatter = new PriceFormatter();\n double tax = subtotal * taxRate;\n double total = subtotal + tax;\n\n return formatter.line(\"Subtotal\", subtotal)\n + \", \" + formatter.line(\"Tax\", tax)\n + \", \" + formatter.line(\"Total\", total)\n + \" (\" + itemCount + \" items)\";\n }\n\n public static void main(String[] args) {\n System.out.println(format(89.97, 0.08, 3));\n }\n}\n```\n\n\n`PriceFormatter` only exists for the duration of one call to `format`. Outside the method, the name is unreachable. That's what makes it a good local class. It's a helper that doesn't need a separate file or a member-level declaration, but it's still big enough to be worth naming.\n\n### Capturing Local Variables\n\nA local class can refer to local variables and parameters of the enclosing method, but only if those variables are **effectively final**. A variable is effectively final when it's assigned once and never reassigned. A local variable can also be explicitly marked `final`, which has the same effect but makes the rule visible.\n\nThe rule exists because the local class might outlive the method that created it. The variable lives on the stack and goes away when the method returns, so the inner class actually gets a copy of the value. If the value could change, two views of the same variable would disagree.\n\n\n```java\npublic class LocalCapture {\n public static Runnable makeGreeter(String customer) {\n String prefix = \"Hello, \";\n\n class Greeter implements Runnable {\n @Override\n public void run() {\n System.out.println(prefix + customer + \"!\");\n }\n }\n\n return new Greeter();\n }\n\n public static void main(String[] args) {\n Runnable greet = makeGreeter(\"Alice\");\n greet.run();\n }\n}\n```\n\n\n`customer` and `prefix` are both used inside `Greeter`. Neither is reassigned, so both are effectively final and the capture works. The `Greeter` instance keeps usable copies of both values even after `makeGreeter` returns.\n\n### What's Wrong With This Code?\n\n\n```java\npublic class BadCapture {\n public static Runnable build(String name) {\n int counter = 0;\n\n class Counter implements Runnable {\n @Override\n public void run() {\n System.out.println(name + \" count: \" + counter);\n }\n }\n\n counter++; // mutation breaks the effectively-final rule\n return new Counter();\n }\n}\n```\n\n\n**Fix:**\n\n`counter` is reassigned after its declaration, so it isn't effectively final. The compiler rejects the reference to `counter` inside `Counter.run()` with: `local variables referenced from an inner class must be final or effectively final`. There are two reasonable fixes. If `counter` truly only needs one value, defer the increment until the captured value is set:\n\n\n```java\npublic class GoodCapture {\n public static Runnable build(String name) {\n int counter = 1;\n\n class Counter implements Runnable {\n @Override\n public void run() {\n System.out.println(name + \" count: \" + counter);\n }\n }\n\n return new Counter();\n }\n\n public static void main(String[] args) {\n build(\"Alice\").run();\n }\n}\n```\n\n\nFor mutable state shared with the local class, store the value in a field of an object and capture the object reference (the reference itself must be effectively final, not the object's fields).\n\n---\n\n# Putting It All Together\n\nA longer example that uses all three nested-class kinds in one place. The `ShoppingCart` has a non-static inner `CartIterator`, a static nested `Builder`, and a local `PriceFormatter` inside a method.\n\n\n```java\npublic class ShoppingCartFull {\n public interface Walker {\n boolean hasNext();\n String next();\n }\n\n private final String customer;\n private final String[] items;\n private final double[] prices;\n private int size;\n\n private ShoppingCartFull(String customer, int capacity) {\n this.customer = customer;\n this.items = new String[capacity];\n this.prices = new double[capacity];\n this.size = 0;\n }\n\n private void addInternal(String name, double price) {\n items[size] = name;\n prices[size] = price;\n size++;\n }\n\n public Walker walker() {\n return new CartIterator();\n }\n\n public String printableTotal(double taxRate) {\n // Local class: only used inside this method.\n class PriceFormatter {\n String money(double amount) {\n return \"$\" + Math.round(amount * 100) / 100.0;\n }\n }\n\n PriceFormatter formatter = new PriceFormatter();\n double subtotal = 0;\n for (int i = 0; i < size; i++) {\n subtotal += prices[i];\n }\n double tax = subtotal * taxRate;\n double total = subtotal + tax;\n\n return customer + \" | subtotal \" + formatter.money(subtotal)\n + \" | tax \" + formatter.money(tax)\n + \" | total \" + formatter.money(total);\n }\n\n // Non-static inner class: needs access to items and size.\n private class CartIterator implements Walker {\n private int cursor = 0;\n\n @Override\n public boolean hasNext() {\n return cursor < size;\n }\n\n @Override\n public String next() {\n String name = items[cursor];\n double price = prices[cursor];\n cursor++;\n return name + \" ($\" + price + \")\";\n }\n }\n\n // Static nested class: builds a cart, doesn't need an existing one.\n public static class Builder {\n private String customer = \"Guest\";\n private int capacity = 10;\n private String[] names = new String[10];\n private double[] prices = new double[10];\n private int count = 0;\n\n public Builder customer(String name) {\n this.customer = name;\n return this;\n }\n\n public Builder capacity(int capacity) {\n this.capacity = capacity;\n this.names = new String[capacity];\n this.prices = new double[capacity];\n return this;\n }\n\n public Builder item(String name, double price) {\n this.names[count] = name;\n this.prices[count] = price;\n this.count++;\n return this;\n }\n\n public ShoppingCartFull build() {\n ShoppingCartFull cart = new ShoppingCartFull(customer, capacity);\n for (int i = 0; i < count; i++) {\n cart.addInternal(names[i], prices[i]);\n }\n return cart;\n }\n }\n\n public static void main(String[] args) {\n ShoppingCartFull cart = new Builder()\n .customer(\"Alice\")\n .capacity(5)\n .item(\"Wireless Mouse\", 29.99)\n .item(\"USB Cable\", 9.99)\n .item(\"Headphones\", 49.99)\n .build();\n\n Walker walker = cart.walker();\n while (walker.hasNext()) {\n System.out.println(walker.next());\n }\n\n System.out.println(cart.printableTotal(0.08));\n }\n}\n```\n\n\nEach nested class earns its spot:\n\n- `CartIterator` walks the cart's private arrays. It needs an enclosing cart instance, so it's a non-static inner class.\n- `Builder` constructs a brand-new cart. There's no cart to attach to yet, so it's a static nested class.\n- `PriceFormatter` only exists during one call to `printableTotal`. It would be noise at the class level, so it lives inside the method.\n\nThe diagram below summarizes the runtime relationship for one cart and its iterator. The arrow from inner to outer is the hidden reference the compiler maintains.\n\n\n```mermaid\nflowchart LR\n OuterObj[\"ShoppingCart instance
customer=Alice
items=...
size=3\"]:::cyan\n InnerObj[\"CartIterator instance
cursor=0\"]:::orange\n BuilderObj[\"Builder instance
(no outer link)\"]:::green\n\n InnerObj -->|hidden outer ref| OuterObj\n BuilderObj -.->|no link| OuterObj\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n```\n\n\nThe non-static inner instance carries that hidden reference, so the JVM treats the outer instance as reachable for as long as any iterator over it is reachable. The builder has no such tie, which is why it can run before any cart exists.\n\n---\n\n# Quick Reference Table\n\nA compact summary of the three kinds:\n\n\n| Kind | Declared as | Holds outer instance? | Can have static members? | Created with |\n| --- | --- | --- | --- | --- |\n| Non-static inner | `class Inner { ... }` inside a class | Yes | No before Java 16; allowed since Java 16 | `outer.new Inner()` (or `new Inner()` inside the outer class) |\n| Static nested | `static class Nested { ... }` inside a class | No | Yes | `new Outer.Nested()` (or `new Nested()` inside the outer class) |\n| Local | `class Local { ... }` inside a method or block | Yes, if inside a non-static context | No | `new Local()` inside the same method or block |\n\n\nThe `Holds outer instance?` column is the most important one. It drives memory behavior, instantiation syntax, and whether the class can access non-static outer members.\n\n---\n\n# Where Anonymous Classes Fit In\n\nThree of the four kinds of nested types are covered above: non-static inner, static nested, and local. The fourth, **anonymous classes**, provides a one-off subclass or interface implementation without giving it a name at all. They were heavily used for one-shot listeners, comparators, and small interface implementations before lambdas arrived.\n\nAnonymous classes share most of the rules with local classes (effective-final capture, no static members, restricted lifetime), but they have their own syntax and a few extra rules.","pageType":"java"}

Inner Classes

Get Premium