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
recordtypes 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:
- the type is level 1 immutable;
- its fields are not modified;
- its fields are either private, level 2 immutable, or of implicitly immutable type;
- 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
String) are of course level 2 immutable.
But unmodifiable variants of collection classes, such as the result of
List.copyOf(), are level 2 immutable as well.
The project proposes simple support classes such as
EventuallyFinal that help propagate eventual immutability throughout your program.