Annotation Type Immutable

@Documented @Target(TYPE) @Retention(RUNTIME) @Inherited public @interface Immutable
The class to which this annotation is applied is immutable.

An object is immutable if its state cannot be observed to change after construction. Immutable objects are inherently thread-safe.

A class is immutable if all instances of that class are immutable. The immutability of a class can only be fully guaranteed if the class is final, otherwise one must ensure all subclasses are also immutable.

A conservative definition of object immutability is:

  • All fields are final;
  • All reference fields are of immutable type, or null;
  • It is properly constructed (the this reference does not escape the constructor).

The requirement that all reference fields be immutable ensures deep immutability, meaning all contained state is also immutable. A weaker property, common with container classes, is shallow immutability, which allows some of the object's fields to point to mutable objects. One example of shallow immutability is guava's ImmutableList, which may contain mutable elements.

It is possible to implement immutable classes with some internal mutable state, as long as callers can never observe changes to that state. For example, some state may be lazily initialized to improve performance.

It is also technically possible to have an immutable object with non-final fields (see the implementation of String.hashCode() for an example), but doing this correctly requires subtle reasoning about safe data races and deep knowledge of the Java Memory Model.

Use of this annotation is validated by Error Prone's immutability analysis, which ensures that all @Immutable-annotated classes are deeply immutable according to the conservative definition above. Non-final classes may be annotated with @Immutable, and any code compiled by Error Prone will be checked to ensure that no mutable subtypes of @Immutable-annotated classes exist.

For more information about immutability, see:

  • Java Concurrency in Practice §3.4
  • Effective Java 3rd Edition §17

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    String[]
    containerOf
    When annotating a generic type as immutable, containerOf specifies which type parameters must be instantiated with immutable types for the container to be deeply immutable.

  • Element Details

    • containerOf

      String[] containerOf
      When annotating a generic type as immutable, containerOf specifies which type parameters must be instantiated with immutable types for the container to be deeply immutable.
      Default:
      {}