Variable Capture

1Concept / Definition

A lambda can use variables from its enclosing scope: local variables and parameters of the enclosing method, and fields of the enclosing instance. Using a local variable is called capturing it. Java allows capturing only local variables that are final or effectively final — never reassigned after initialisation — and the lambda receives a copy of the value, not access to the variable itself. Fields are accessed through the captured this and have no such restriction.

2Why It Exists

Local variables live in a method's stack frame, which disappears when the method returns — but a lambda can outlive it (stored, returned, run on another thread). Copying the value solves lifetime; requiring the variable never to change makes the copy indistinguishable from the variable, so there is no confusing difference between "the lambda's copy" and "the real variable". It also prevents unsynchronised sharing of mutable locals between threads.

3Core Concepts

Effectively final variables

Since Java 8 a local variable does not need the final keyword to be captured: it is enough that it is assigned exactly once. Assigning it again anywhere in the method — before or after the lambda — makes capture a compile error ("local variables referenced from a lambda expression must be final or effectively final"). The same rule applies to anonymous and local classes since Java 8.

Capturing state

Three kinds of state are reachable from a lambda. Captured locals are copied values; if a value is a reference to a mutable object, the object can still be mutated through it, because only the reference is final. Instance fields are read and written through the captured this; the lambda sees their current values, not a copy. Static fields are accessed directly. Mutating shared state from lambdas — through fields, mutable holders such as int[] or AtomicInteger, or external collections — is legal but defeats the purpose and is unsafe in parallel code.

A lambda does not introduce a new scope: this refers to the enclosing instance, and parameters or locals in the lambda may not shadow local variables of the enclosing method. This is the opposite of anonymous classes.

4How It Works Internally

Captured values are passed to the lambda factory at creation and stored in final fields of the hidden class instance; the synthetic method receives them as extra leading parameters. A lambda that uses an instance field or method captures this. Consequently a non-capturing lambda is a shared singleton, while a capturing lambda allocates a new object every time the lambda expression is evaluated — for example, inside a loop.

5APIs / Features / Syntax

Capture is not an API but a set of language rules, and they apply the same way to lambdas, anonymous classes and local classes. Any local name in scope can be captured if it is final or effectively final: method and constructor parameters, ordinary locals, the enhanced-for variable, catch parameters, try-with-resources variables (implicitly final) and pattern variables introduced by instanceof or a switch case. Fields, this and, inside a lambda, super are reached through the enclosing instance rather than copied.

void handle(Request req, List<Order> orders) {
    String tenant = req.tenant();               // effectively final
    orders.forEach(o -> audit(tenant, o));      // OK

    if (req.body() instanceof Payment p) {      // pattern variable
        executor.submit(() -> settle(p));       // OK: not reassigned
    }

    try (var conn = pool.acquire()) {           // implicitly final
        orders.forEach(o -> conn.queue(o));     // OK
    } catch (SQLException e) {
        executor.submit(() -> report(e));       // OK: not reassigned
    }

    int retries = 0;
    retries++;                                  // reassigned
    // Runnable r = () -> log(retries);         // compile error
}

Method references capture eagerly

A bound method reference such as order::ship evaluates its receiver when the reference is created, not when it is invoked. If order is null, the NullPointerException is thrown at creation; if the variable later points elsewhere, the reference still uses the original object. The equivalent lambda () -> order.ship() reads the variable lazily, which is why it is subject to the effectively final rule while the receiver expression of a method reference is not.

Since Java 22 an unnamed variable _ can stand in for a lambda parameter the body does not use, as in map.forEach((_, v) -> total.add(v)), which makes clear that nothing is captured or read from it.

6Practical Examples

// Effectively final: fine
void discount(List<Order> orders, BigDecimal rate) {
    BigDecimal factor = BigDecimal.ONE.subtract(rate);          // assigned once
    orders.replaceAll(o -> o.withTotal(o.total().multiply(factor)));
}

// Accumulating: don't mutate captured holders; reduce instead
BigDecimal sum = orders.stream().map(Order::total).reduce(BigDecimal.ZERO, BigDecimal::add);

// Loop variables: the enhanced-for variable is effectively final per iteration
for (Order o : orders) executor.submit(() -> ship(o));       // OK
for (int i = 0; i < n; i++) {
    int index = i;  // copy needed: i is reassigned
    executor.submit(() -> process(index));
}

// Avoid capturing 'this' in long-lived registrations
class Dashboard {
    private final Map<String, Widget> widgets = new HashMap<>();   // large
    void start(EventBus bus) {
        bus.subscribe(Tick.class, t -> refresh());             // captures this
    }
    void stop(EventBus bus) { bus.unsubscribeAll(this); }  // must be called
}

7Common Problems & Mistakes

• Using int[], AtomicInteger or an external list to accumulate inside forEach — hides shared mutation; use reductions and collectors.
• Capturing a mutable object and assuming the lambda sees a snapshot — it sees later mutations.
• Implicitly capturing this in lambdas registered with long-lived objects — keeps the whole enclosing object alive.
• Capturing a classic for loop index — compile error; copy to an effectively final local.
• Capturing large objects (entire request contexts) in lambdas scheduled for later execution — memory and data-leak risk.

8Performance & Production Considerations

Capturing lambdas allocate on each evaluation; in very hot loops, hoisting the lambda out of the loop or making it non-capturing (passing data as parameters) avoids the allocation, although escape analysis often removes it anyway. Heap dumps of leaking services frequently show $$Lambda hidden-class instances holding references to controllers or sessions: the listener or callback registry that holds them is the real culprit.

9Architecture & Design Considerations

Capture rules push code toward stateless behaviour, which is exactly what concurrent and distributed execution needs. When lambdas are handed to executors, schedulers, reactive pipelines or event buses, treat what they capture as part of the contract: capture immutable values, never request-scoped mutable objects, and make lifetimes explicit by unsubscribing or using weak listeners where the registry outlives the subscriber.

10Interview Questions & Answers