What is the advantage of annotating an immutable Java class with @Immutable?

Question

I get the concept of immutability, and why it is a good idea to make DTOs immutable.

I also notice that Java has an @Immutable annotation that we can use to annotate immutable classes.

My question is: what does annotating a Java class as @Immutable give us? Are there any library features that only work on classes annotated in this way?

Solution 1

The annotation documents the fact that your class is immutable and tells the users of the class that you have followed the contract defined in the annotation javadoc. It is also frequent to simply include a comment directly in the javadoc: this is the approach chosen by the JDK, see for example the javadoc of LocalDate.

Some static analysis tools such as FindBugs can also use that annotation and verify that the class really is immutable. If you forgot to make a public field final for example, FindBugs will emit a warning.

Solution 2

The main benefit is documentation. The JCIP annotations were introduced without implementations, on the theory that they offered documentation benefits from being written even if they were not checked.

I do not know of any current library feature that depends on your class being annotated as @Immutable.

There are two ways that existence of an @Immutable annotation could potentially affect your program.

1. At compile time, your program could fail to compile because it did not respect the library's contract -- in other words, the compiler issues a warning if your program contains an immutability bug. This is how the Checker Framework's IGJ Immutability Checker works. Alternately, you could run an additional analysis at build time and fail the build if the analysis fails. This is how FindBugs works (also see MutabilityDetector4FindBugs, a third-party add-on).

2. At run time, the library could use reflection or a similar analysis to read your program's classfiles. The library could behave differently (such as throwing an error) depending on whether it finds @Immutable annotations.

A caution: there are multiple, equally valid definitions of @Immutable, and it's easy to mix them up which leads to confusion. For instance, is the immutability with respect to the Java heap (no changes whatsoever are permitted to any field), or with respect to the abstract value (internal representation changes are permitted so long as no client can observe them)? As another example, is the immutability shallow (no changes to this object, but changes are permitted to objects it references) or transitive (no changes to this object or to any object that it references)? Does the immutability prevent changes through the given reference or variable, or does it also prevent changes through aliases? Be sure that you understand what choices your tool has made.

Solution 3

what does annotating a Java class as @Immutable give us?

Annotation in Java does not do anything itself, but they are used by external tools. Take a look at very good inspections for such annotations in IntelliJ IDEA.