Introduction to Immutables

1. Introduction

In this article we will be showing how to work with the Immutables library.

Immutables consists of annotations and annotation processors for generating and working with serializable and customizable immutable objects.

2. Maven Dependencies

In order to use Immutables in your project, you need to add the following dependency to the dependencies section of your pom.xml file:

<dependency>
    <groupId>org.immutables</groupId>
    <artifactId>value</artifactId>
    <version>2.2.10</version>
    <scope>provided</scope>
</dependency>

As this artifact is not required during runtime, so it’s advisable to specify the provided scope.

The newest version of the library can be found here.

3. Immutables

The library generates immutable objects from abstract types: Interface, Class, Annotation.

The key to achieving this is the proper use of @Value.Immutable annotation. It generates an immutable version of an annotated type and prefixes its name with the Immutable keyword.

If we try to generate an immutable version of class named “X“, it will generate a class named “ImmutableX”. Generated classes are not recursively-immutable, so it’s good to keep that in mind.

And a quick note – because Immutables utilizes annotation processing, you need to remember to enable annotation processing in your IDE.

3.1. Using @Value.Immutable With Abstract Classes and Interfaces

Let’s create a simple abstract class Person consisting of two abstract accessor methods representing the to-be-generated fields, and then annotate the class with the @Value.Immutable annotation:

@Value.Immutable
public abstract class Person {

    abstract String getName();
    abstract Integer getAge();

}

After annotation processing is done, we can find a ready-to-use, newly-generated ImmutablePerson class in a target/generated-sources directory:

@Generated({"Immutables.generator", "Person"})
public final class ImmutablePerson extends Person {

    private final String name;
    private final Integer age;

    private ImmutablePerson(String name, Integer age) {
        this.name = name;
        this.age = age;
    }

    @Override
    String getName() {
        return name;
    }

    @Override
    Integer getAge() {
        return age;
    }

    // toString, hashcode, equals, copyOf and Builder omitted

}

The generated class comes with implemented toString, hashcode, equals methods and with a stepbuilder ImmutablePerson.Builder. Notice that the generated constructor has private access.

In order to construct an instance of ImmutablePerson class, we need to use the builder or static method ImmutablePerson.copyOf, which can create an ImmutablePerson copy from a Person object.

If we want to construct an instance using the builder, we can simply code:

ImmutablePerson john = ImmutablePerson.builder()
  .age(42)
  .name("John")
  .build();

Generated classes are immutable which means they can’t be modified. If you want to modify an already existing object, you can use one of the “withX” methods, which do not modify an original object, but create a new instance with a modified field.

Let’s update john’s age and create a new john43 object:

ImmutablePerson john43 = john.withAge(43);

In such a case the following assertions will be true:

assertThat(john).isNotSameAs(john43);

assertThat(john.getAge()).isEqualTo(42);

4. Additional Utilities

Such class generation would not be very useful without being able to customize it. Immutables library comes with a set of additional annotations that can be used for customizing @Value.Immutable‘s output. To see all of them, please refer to Immutables’ documentation.

4.1. The @Value.Parameter Annotation

The @Value.Parameter annotation can be used for specifying fields, for which constructor method should be generated.

If you annotate your class like this:

@Value.Immutable
public abstract class Person {

    @Value.Parameter
    abstract String getName();

    @Value.Parameter
    abstract Integer getAge();
}

It will be possible to instantiate it in the following way:

ImmutablePerson.of("John", 42);

4.2. The @Value.Default Annotation

The @Value.Default annotation allows you to specify a default value that should be used when an initial value is not provided. In order to do this, you need to create a non-abstract accessor method returning a fixed value and annotate it with @Value.Default:

@Value.Immutable
public abstract class Person {

    abstract String getName();

    @Value.Default
    Integer getAge() {
        return 42;
    }
}

The following assertion will be true:

ImmutablePerson john = ImmutablePerson.builder()
  .name("John")
  .build();

assertThat(john.getAge()).isEqualTo(42);

4.3. The @Value.Auxiliary Annotation

The @Value.Auxiliary annotation can be used for annotating a property that will be stored in an object’s instance, but will be ignored by equals, hashCode and toString implementations.

If you annotate your class like this:

@Value.Immutable
public abstract class Person {

    abstract String getName();
    abstract Integer getAge();

    @Value.Auxiliary
    abstract String getAuxiliaryField();

}

The following assertions will be true when using the auxiliary field:

ImmutablePerson john1 = ImmutablePerson.builder()
  .name("John")
  .age(42)
  .auxiliaryField("Value1")
  .build();

ImmutablePerson john2 = ImmutablePerson.builder()
  .name("John")
  .age(42)
  .auxiliaryField("Value2")
  .build();

assertThat(john1.equals(john2)).isTrue();

assertThat(john1.toString()).isEqualTo(john2.toString());

assertThat(john1.hashCode()).isEqualTo(john2.hashCode());

4.4. The @Value.Immutable(prehash = true) Annotation

Since our generated classes are immutable and can never get modified, hashCode results will always remain the same and can be computed only once during the object’s instantiation.

If you annotate your class like this:

@Value.Immutable(prehash = true)
public abstract class Person {

    abstract String getName();
    abstract Integer getAge();

}

When inspecting the generated class, you can see that hashcode value is now precomputed and stored in a field:

@Generated({"Immutables.generator", "Person"})
public final class ImmutablePerson extends Person {

    private final String name;
    private final Integer age;
    private final int hashCode;

    private ImmutablePerson(String name, Integer age) {
        this.name = name;
        this.age = age;
        this.hashCode = computeHashCode();
    }

    // generated methods
 
    @Override
    public int hashCode() {
        return hashCode;
    }
}

The hashCode() method returns a precomputed hashcode generated when the object was constructed.

5. Conclusion

In this quick tutorial we showed the basic workings of the Immutables library.

All source code and unit tests in the article can be found in the GitHub repository.