Java nested, inner, local and anonymous classes

Compile a playlist class and the program that plays it, two source files, and javac writes six class files. Four of them hold classes declared inside other code: a nested classnested class: A class declared inside another class or inside a method. It is static nested, inner, local or anonymous, and it may use the private members of the classes around it. is declared inside another class or a method, and Java has four kinds: static nestedstatic nested class: A class declared with static inside another class. It has no enclosing object, so new Outer.Nested() needs none, and it reaches the outer class's instance members only through a reference it is given., innerinner class: A nested class declared without static. Each of its objects belongs to one object of the outer class, its enclosing instance, which it can name as Outer.this; local and anonymous classes are inner classes too., locallocal class: A class declared inside a method or another block. It is known only there, and it may read the block's local variables and parameters that are final or effectively final. and anonymousanonymous class: A class without a name, declared and instantiated in one expression, as in new Comparator<String>() { … }. It implements an interface or extends a class, and javac names its class file Outer$1, Outer$2 and so on..

Nesting keeps a helper next to the only code that uses it, and lets it read the outer class’s private members. The kinds differ in one important way: inner, local and anonymous classes can see an enclosing object or local variables, while a static nested class cannot. That difference decides memory use, what the class may capture and what this means inside it. This lesson puts all four kinds into one class, shows with reflection the hidden reference an inner class keeps, rewrites an anonymous class as a lambdaA short way to write an object of an interface that has one abstract method: the parameters, an arrow and the body, as in (x, y) -> Integer.compare(x, y). The module on lambdas covers them in depth., and shows why every class in a compact source file is an inner class.

Java has four places to declare a class inside another

A static nested class is declared with static inside a class and is an ordinary class that happens to live in another’s namespace. An inner class is declared inside a class without static, and each of its objects belongs to one object of the outer class. A local class is declared inside a method or another block, and an anonymous class is declared and created in one expression, without a name. Playlist holds one nested class of each of the first three kinds, and Main adds an anonymous comparator:

import java.util.ArrayList;
import java.util.Iterator;
import java.util.List;
import java.util.NoSuchElementException;

/** A playlist with one class of each kind inside it. */
final class Playlist implements Iterable<String> {
    private final List<String> songs;

    private Playlist(List<String> songs) {
        this.songs = List.copyOf(songs);
    }

    /** Static nested: needs no Playlist object, and builds one step by step. */
    static final class Builder {
        private final List<String> songs = new ArrayList<>();

        Builder add(String song) {
            songs.add(song);
            return this;
        }

        Playlist build() {
            return new Playlist(songs);
        }
    }

    /** Inner: every Cursor belongs to one Playlist object and reads that playlist's songs. */
    private final class Cursor implements Iterator<String> {
        private int next = 0;

        @Override
        public boolean hasNext() {
            return next < songs.size();
        }

        @Override
        public String next() {
            if (!hasNext()) throw new NoSuchElementException();
            return songs.get(next++);
        }
    }

    @Override
    public Iterator<String> iterator() {
        return new Cursor();              // the new Cursor is tied to this playlist
    }

    /** Local: declared inside the method, and it may read the method's effectively final variables. */
    List<String> longerThan(int letters) {
        class Filter {
            boolean keep(String song) {
                return song.length() > letters;
            }
        }
        Filter filter = new Filter();
        List<String> kept = new ArrayList<>();
        for (String song : songs) {
            if (filter.keep(song)) kept.add(song);
        }
        return kept;
    }
}

void main() {
    Playlist playlist = new Playlist.Builder().add("Monsoon Song").add("Rain").add("Night Train Home").build();
    for (String song : playlist) IO.println("plays " + song);             // the for-each loop uses a Cursor
    IO.println("longer than 10 characters: " + playlist.longerThan(10));

    // Anonymous: a class without a name, declared and instantiated in one expression.
    Comparator<String> byLength = new Comparator<String>() {
        @Override
        public int compare(String a, String b) {
            return Integer.compare(a.length(), b.length());
        }
    };
    List<String> sorted = new ArrayList<>();
    playlist.forEach(sorted::add);
    sorted.sort(byLength);
    IO.println("shortest first: " + sorted);
}

from session import run

# The program, then the class files javac writes for it: one per class, nested ones included.
run("""
java kinds/Main.java
javac -d classes kinds/Main.java kinds/Playlist.java
ls classes
""")

# openjdk version "25.0.4.1" LTS
$ java kinds/Main.java
plays Monsoon Song
plays Rain
plays Night Train Home
longer than 10 characters: [Monsoon Song, Night Train Home]
shortest first: [Rain, Monsoon Song, Night Train Home]
$ javac -d classes kinds/Main.java kinds/Playlist.java
$ ls classes
Main.class
Main$1.class
Playlist.class
Playlist$1Filter.class
Playlist$Builder.class
Playlist$Cursor.class

• Builder is static nested. new Playlist.Builder() needs no playlist, which is the point: it exists to create one. Being nested, it may call the private constructor of Playlist. Builders and small helper types are the typical static nested classes.
• Cursor is inner. iterator() returns new Cursor(), and that cursor reads the songs field of the very playlist that created it. The for loop over a playlist uses one, without ever naming the class.
• Filter is local. It exists only inside longerThan, and it reads the method’s parameter letters.
• The comparator in Main is anonymous. new Comparator<String>() { … } declares a class that implements the interface and creates its only object in the same expression.

The listing of classes shows that each one is a real class with its own class file. Member classes are named Outer$Member, local classes Outer$1Filter and anonymous classes Outer$1, Outer$2 and so on. Those names appear in stack traces, so it pays to recognise them.

An inner class gets a hidden field for its outer object

An inner object belongs to an outer object, its enclosing instanceenclosing instance: The object of the outer class that an inner object belongs to. The compiler passes it to the inner class's constructor and, when the inner class uses it, keeps it in a hidden field named this$0., so the compiler has to connect them. It passes the outer object to the inner class’s constructor and, when the inner class actually uses it, stores it in a syntheticMade by the compiler rather than written in the source code, such as the field that holds an inner object's outer object. field named this$0. Reflection shows the difference between three nested classes of a Screen:

/** Three nested classes of Screen, to see which ones keep a reference to a Screen object. */
final class Screen {
    private final String title;

    Screen(String title) {
        this.title = title;
    }

    /** Inner, and it reads the field of its Screen. */
    final class TitleLabel {
        String text() {
            return "[" + title + "]";
        }
    }

    /** Inner, but it never touches its Screen. */
    final class Spacer {
        String text() {
            return "     ";
        }
    }

    /** Static nested: no Screen involved at all. */
    static final class Style {
        String text() {
            return "bold";
        }
    }
}

// What reflection shows about the fields and constructors the compiler gave each nested class.
void main() throws Exception {
    for (Class<?> c : List.of(Screen.TitleLabel.class, Screen.Spacer.class, Screen.Style.class)) {
        IO.println(c.getName());
        IO.println("  fields:      " + Arrays.toString(c.getDeclaredFields()));
        IO.println("  constructor: " + Arrays.toString(c.getDeclaredConstructors()));
    }

    Screen home = new Screen("Home");
    Screen.TitleLabel label = home.new TitleLabel();     // an inner object needs an outer one
    Field outer = Screen.TitleLabel.class.getDeclaredField("this$0");
    outer.setAccessible(true);
    IO.println("label's hidden field holds home: " + (outer.get(label) == home));
    IO.println("label.text() = " + label.text());
}

Screen$TitleLabel
  fields:      [final Screen Screen$TitleLabel.this$0]
  constructor: [Screen$TitleLabel(Screen)]
Screen$Spacer
  fields:      []
  constructor: [Screen$Spacer(Screen)]
Screen$Style
  fields:      []
  constructor: [Screen$Style()]
label's hidden field holds home: true
label.text() = [Home]

• TitleLabel reads title, so it has the field final Screen this$0, and the run confirms that it holds the very screen the label was created from. home.new TitleLabel() is how code outside the class names that screen.
• Spacer never touches its screen, and it has no field at all. The JDK 18 release notes describe the change: before JDK 18, javac always generated the field; since then it omits it when the inner class does not use its enclosing instance. The constructor still takes a Screen, so new Spacer() still needs one.
• Style is static nested: no field, and a constructor without a Screen parameter.

Step through the second half of the program, where the label is created and asked for its text:

The hidden field keeps the outer object alive

The reference matters for memory. As long as anything can reach a TitleLabel, its screen cannot be garbage collected, together with everything the screen holds:

That is the classic leak of inner classes: an inner object registered as a listener in some long-lived list, or kept in a cache, keeps its whole outer object alive long after the outer object was meant to go. Step through it as it happens:

The release note makes the same point: omitting unused this$0 fields lets outer objects be collected sooner. The cure is the first rule of choosing a kind: make a nested class static unless it really needs the outer object. A static nested class cannot keep one by accident.

Serialization is the other reason to avoid inner classes where you can. The Learn Java guide on nested classes says that serializing inner classes, including local and anonymous ones, is strongly discouraged, because the synthetic constructs the compiler adds for them can differ between compilers.

Local and anonymous classes capture only effectively final variables

A local or anonymous class, and a lambda, may read the local variables and parameters of the method around it, but only if they are final or effectively finaleffectively final: Said of a local variable or parameter that is never changed after it is assigned, so adding final to it would not cause a compile error. Local and anonymous classes and lambdas may read only such variables or final ones.: assigned once and never changed. The specification lists the exact conditions (never assigned again, never the operand of ++ or --) and adds a quick test: adding final to an effectively final variable causes no compile error.

void main() {
    int limit = 3;
    class Check {
        boolean ok(int n) {
            return n <= limit;            // reads a local variable of main
        }
    }
    limit = 4;                            // so this assignment is an error
    IO.println(new Check().ok(4));
}

void main() {
    int count = 0;
    Runnable report = () -> IO.println("count is " + count);
    count++;                              // the same rule for a lambda
    report.run();
}

from session import run

run("""
!java capture/LocalClass.java
!java capture/Lambda.java
""")

# openjdk version "25.0.4.1" LTS
$ java capture/LocalClass.java
capture/LocalClass.java:5: error: local variables referenced from an inner class must be final or effectively final
            return n <= limit;            // reads a local variable of main
                        ^
1 error
error: compilation failed
[exit status 1]
$ java capture/Lambda.java
capture/Lambda.java:3: error: local variables referenced from a lambda expression must be final or effectively final
    Runnable report = () -> IO.println("count is " + count);
                                                     ^
1 error
error: compilation failed
[exit status 1]

The local class reads limit, and the later limit = 4 makes it a variable that changes, which the compiler refuses. Its message calls the local class an inner class, which by the specification’s definition every local class is, apart from local records, enums and interfaces. The lambda gets the same error for count++. The specification gives the reason: capturing local variables that keep changing would likely introduce concurrency problems. In the compiled code, the class or lambda keeps a copy of the value taken when it was created, so a variable that changed afterwards would silently disagree with its copy. When you need a value that changes, keep it in a field, an array element or an object such as an AtomicInteger, and capture the reference to that.

A one-method anonymous class is usually better as a lambda

An anonymous class that implements an interface with a single abstract method, such as Comparator, Runnable or Predicate, can almost always be written as a lambda, and often as a method referenceA lambda shortened to the one method it calls, written with two colons: Song::seconds stands for song -> song.seconds().:

// One sort written three ways: an anonymous class, a lambda, and a comparator built from a method reference.
record Song(String title, int seconds) {}

void main() {
    List<Song> songs = List.of(new Song("Rain", 214), new Song("Monsoon Song", 187), new Song("Night Train Home", 301));

    List<Song> a = new ArrayList<>(songs);
    a.sort(new Comparator<Song>() {
        @Override
        public int compare(Song x, Song y) {
            return Integer.compare(x.seconds(), y.seconds());
        }
    });

    List<Song> b = new ArrayList<>(songs);
    b.sort((x, y) -> Integer.compare(x.seconds(), y.seconds()));

    List<Song> c = new ArrayList<>(songs);
    c.sort(Comparator.comparingInt(Song::seconds));

    IO.println("anonymous class: " + titles(a));
    IO.println("lambda:          " + titles(b));
    IO.println("comparingInt:    " + titles(c));
}

List<String> titles(List<Song> songs) {
    return songs.stream().map(Song::title).toList();
}

anonymous class: [Monsoon Song, Rain, Night Train Home]
lambda:          [Monsoon Song, Rain, Night Train Home]
comparingInt:    [Monsoon Song, Rain, Night Train Home]

All three sorts print the same order. The lambda drops the class declaration, the method signature and the types of the parameters, and Comparator.comparingInt(Song::seconds) states what is compared instead of how. That is the form to prefer for comparators.

The rewrite is not purely mechanical in one respect: this means something else in the two forms.

/** What `this` means inside an anonymous class and inside a lambda. */
final class Screen {
    private final String name;

    Screen(String name) {
        this.name = name;
    }

    Runnable anonymous() {
        return new Runnable() {
            @Override
            public void run() {
                IO.println("anonymous: this is " + this + "; Screen.this is " + Screen.this);
            }

            @Override
            public String toString() {
                return "the anonymous Runnable";
            }
        };
    }

    Runnable lambda() {
        return () -> IO.println("lambda:    this is " + this);
    }

    @Override
    public String toString() {
        return "Screen " + name;
    }
}

void main() {
    Screen home = new Screen("home");
    home.anonymous().run();
    home.lambda().run();
}

anonymous: this is the anonymous Runnable; Screen.this is Screen home
lambda:    this is Screen home

Inside the anonymous class, this is the anonymous object itself, which is why its own toString prints, and Screen.this names the enclosing screen. Inside the lambda, this is the screen: the specification says that this and names in a lambda body mean the same as in the surrounding code. Keep an anonymous class when you need this to be the object itself, when the object needs fields of its own, when it must implement more than one method, or when it extends a class rather than implementing an interface.

Every class in a compact source file is an inner class

A compact source file, one whose methods and fields are written at the top level of the file instead of inside a class declaration, is compiled into an implicitly declared class, usually named after the file. The specification says that every class declared in such a file is a member of that implicit class. A plain class declared there is therefore not top level but an inner class, while records, enums and interfaces are implicitly static:

// In a compact source file, every class you declare is a member of the implicitly declared class Main.
class Tally {
    int count;
}

record Score(String player, int points) {}

void main() {
    for (Class<?> c : List.of(Tally.class, Score.class)) {
        IO.println(c.getName() + ": member of " + c.getEnclosingClass().getName()
                + ", static " + Modifier.isStatic(c.getModifiers()));
    }
    Tally tally = new Tally();            // fine: main is an instance method, so there is a Main object
    tally.count++;
    IO.println("tally " + tally.count + ", " + new Score("Asha", 42));
}

// The same inner class, created from a static method of the compact file.
class Tally {
    int count;
}

static Tally fresh() {
    return new Tally();                   // no Main object here, so no enclosing instance for Tally
}

void main() {
    IO.println(fresh().count);
}

from session import run

run("""
java compact/Main.java
!java compact/StaticHelper.java
""")

# openjdk version "25.0.4.1" LTS
$ java compact/Main.java
Main$Tally: member of Main, static false
Main$Score: member of Main, static true
tally 1, Score[player=Asha, points=42]
$ java compact/StaticHelper.java
compact/StaticHelper.java:7: error: non-static variable this cannot be referenced from a static context
    return new Tally();                   // no Main object here, so no enclosing instance for Tally
           ^
1 error
error: compilation failed
[exit status 1]

Tally is Main$Tally and not static; Score is Main$Score and static. Inside void main(), which is an instance method, there is a Main object to attach a new Tally to, so everything works. A static method of the file has no such object, and javac refuses new Tally() there with the message non-static variable this cannot be referenced from a static context. The fix is either to declare static class Tally, or to move the class into its own file, as the examples of this module do once a program grows.

Start from a static nested class, and add the outer object only when needed

Four questions about the helper you need decide its kind. Answer them in the table: each answer rules kinds out or adds a caveat, with the reason, and the cells carry this lesson’s own classes:

Local and anonymous classes and lambdas can also read the effectively final local variables around them; static nested and inner classes cannot.

Read the kinds from top to bottom as a preference: use a static nested class unless the class needs the outer object, an inner class when it does, a local class when only one method needs it, and an anonymous class or a lambda for a one-off object, preferring the lambda whenever the interface has one method.

Practise: a range with an inner iterator

Range holds the integers from a start value, counting up by a step, while they stay below an end value. It is Iterable, so a for loop can walk it. Its Builder is a static nested class, and its iterator should be an inner class that reads the range’s fields:

import java.util.Collections;
import java.util.Iterator;

/**
 * The ints from start, counting up by step, while they stay below end:
 * Range.builder().from(1).to(10).step(3).build() holds 1, 4 and 7.
 */
final class Range implements Iterable<Integer> {
    private final int start;
    private final int end;
    private final int step;

    private Range(int start, int end, int step) {
        this.start = start;
        this.end = end;
        this.step = step;
    }

    static Builder builder() {
        return new Builder();
    }

    /** Your turn: return a new object of an inner class that walks start, start + step, ... while below end. */
    @Override
    public Iterator<Integer> iterator() {
        return Collections.emptyIterator();
    }

    /** Collects the three values, then builds the Range. The step starts at 1. */
    static final class Builder {
        private int start;
        private int end;
        private int step = 1;

        Builder from(int start) {
            this.start = start;
            return this;
        }

        Builder to(int end) {
            this.end = end;
            return this;
        }

        /** Your turn: keep the step, and refuse 0 or less with an IllegalArgumentException. */
        Builder step(int step) {
            return this;
        }

        Range build() {
            return new Range(start, end, step);
        }
    }
}

// Sample checks for Range. Edit Range.java, then run: java range/RangeChecks.java
int passed = 0;
int total = 0;

/** Runs one check; an exception counts as a failure, so every check gets its line. */
void check(String what, BooleanSupplier test) {
    total++;
    boolean ok;
    try {
        ok = test.getAsBoolean();
    } catch (RuntimeException e) {
        ok = false;
        what += " (threw " + e.getClass().getSimpleName() + ")";
    }
    if (ok) passed++;
    IO.println((ok ? "pass  " : "FAIL  ") + what);
}

List<Integer> values(Range range) {
    List<Integer> out = new ArrayList<>();
    for (int n : range) {
        out.add(n);
        if (out.size() > 100) break;      // a broken iterator must not run forever
    }
    return out;
}

boolean throwsIllegalArgument(Runnable action) {
    try {
        action.run();
        return false;
    } catch (IllegalArgumentException e) {
        return true;
    }
}

void main() {
    check("from 1 to 10 step 3 gives [1, 4, 7]",
            () -> values(Range.builder().from(1).to(10).step(3).build()).equals(List.of(1, 4, 7)));
    check("the step defaults to 1", () -> values(Range.builder().from(0).to(4).build()).equals(List.of(0, 1, 2, 3)));
    check("from 5 to 5 is empty", () -> values(Range.builder().from(5).to(5).build()).isEmpty());
    check("a step of 0 is refused", () -> throwsIllegalArgument(() -> Range.builder().step(0)));

    Range three = Range.builder().from(0).to(3).build();
    check("two iterators of one range move independently", () -> {
        Iterator<Integer> first = three.iterator();
        Iterator<Integer> second = three.iterator();
        first.next();
        first.next();
        return second.next() == 0 && first.next() == 2;
    });
    check("an exhausted iterator says hasNext false, and next throws NoSuchElementException", () -> {
        Iterator<Integer> it = three.iterator();
        while (it.hasNext()) it.next();
        try {
            it.next();
            return false;
        } catch (NoSuchElementException e) {
            return true;
        }
    });
    check("near Integer.MAX_VALUE it stops instead of wrapping around", () -> values(
            Range.builder().from(Integer.MAX_VALUE - 1).to(Integer.MAX_VALUE).step(5).build())
            .equals(List.of(Integer.MAX_VALUE - 1)));
    check("the iterator is an inner class of Range", () -> {
        Class<?> walker = three.iterator().getClass();
        return walker.getEnclosingClass() == Range.class && walker.isMemberClass()
                && !Modifier.isStatic(walker.getModifiers());
    });
    check("Builder is a static nested class", () -> Modifier.isStatic(Range.Builder.class.getModifiers()));

    IO.println(passed + " of " + total + " checks passed");
    if (passed < total) System.exit(1);
}

FAIL  from 1 to 10 step 3 gives [1, 4, 7]
FAIL  the step defaults to 1
pass  from 5 to 5 is empty
FAIL  a step of 0 is refused
FAIL  two iterators of one range move independently (threw NoSuchElementException)
pass  an exhausted iterator says hasNext false, and next throws NoSuchElementException
FAIL  near Integer.MAX_VALUE it stops instead of wrapping around
FAIL  the iterator is an inner class of Range
pass  Builder is a static nested class
3 of 9 checks passed

Edit Range.java until java range/RangeChecks.java prints 9 of 9 checks passed:

1. In Builder.step, throw an IllegalArgumentException for a step of 0 or less, and keep the step otherwise.
2. Add a private final class inside Range that implements Iterator<Integer>, with a field for the next value. hasNext() is true while that value is below end; next() throws NoSuchElementException when there is nothing left, as the Iterator documentation requires, and otherwise returns the value and adds the step.
3. Return a new object of that class from iterator(), so that two iterators never share a position.

The check near Integer.MAX_VALUE is the subtle one: adding the step to an int that is close to the maximum wraps around to a negative number, which is still below end. Keep the next value in a long.

Then go over the seven ideas of this lesson question by question, from the four kinds to the choice between them. Practice begins where your answers above went wrong most often, and the reason for each choice shows as you pick it:

Interview questions

Fresher · What is the difference between a static nested class and an inner class in Java?

A static nested class is declared with static inside another class and has no connection to any object of that class: you create it with new Outer.Nested(), and it can only reach the outer class’s instance members through a reference you give it. An inner class is declared without static, and every inner object belongs to one outer object: you create it with outer.new Inner(), or with plain new Inner() inside an instance method of the outer class, and its methods can read that outer object’s fields directly or as Outer.this. To make that work, the compiler passes the outer object to the inner constructor and keeps it in a hidden field when the inner class uses it. A good answer adds the consequence: an inner object keeps its outer object reachable, so prefer a static nested class unless the class really needs the outer object.

Two longer questions of this module start from this lesson: screens that stay in memory after they are closed, and the iterator of a ring buffer that must notice when the buffer changes.

Key takeaways

• A nested class is static nested, inner, local or anonymous; inner, local and anonymous classes can see an enclosing object, and a static nested class cannot.
• An inner class receives its outer object in its constructor and keeps it in a hidden this$0 field when it uses it; since JDK 18 the field is left out when the inner class does not.
• An inner object keeps its outer object reachable, which is the usual cause of inner-class memory leaks, so make nested classes static unless they need the outer object.
• Local and anonymous classes and lambdas can read only effectively final local variables, because they keep a copy of the value.
• An anonymous class for a one-method interface is usually better as a lambda or method reference; inside a lambda, this is the enclosing object, not the lambda.
• Every class declared in a compact source file is a member of the implicit class, so a plain class there is an inner class and cannot be created from a static method.