e2immu concepts

The best place to start reading about the immutability concepts is:

There’s also a slide deck covering the basic concepts.


  • modification: changes to the object graph of an object’s fields.

  • container: a type which does not make modifications to the parameters of its constructors and non-private methods. You can use it as safe storage for your objects.

  • level 1 immutable: all fields are effectively final (either explicitly, or only modified during the construction phase). Java record types are a nice example.

  • field of implicitly immutable type: when its type can be replaced by Object. The best example are fields of unbound parameter type <T>.

  • independence: a modification to one object has no effect on the other object. Fields of implicitly immutable type cannot be dependent, because the type has no means of modifying them.

  • a type is level 2 immutable when the following four criteria are met:

    1. the type is level 1 immutable;
    2. its fields are not modified;
    3. its fields are either private, level 2 immutable, or of implicitly immutable type;
    4. constructor parameters are independent of the fields, as are the return values of non-private methods
  • eventually immutable: immutability (level 1 or 2) is achieved after a field changes from a before state into an after or final state. This blocks a number of modifying methods, which makes the type effectively immutable.

Deeply immutable types (like Object, String) are of course level 2 immutable. But unmodifiable variants of collection classes, such as the result of Set.of() and List.copyOf(), are level 2 immutable as well.

The project proposes simple support classes such as SetOnce and EventuallyFinal that help propagate eventual immutability throughout your program.

Edit this page on GitHub