Immutability Library: Immutables


In the previous article, Immutability with Lombok builder pattern, we discovered how we can achieve immutable objects in a very easy and convenient way. In this article, we are going to look at an alternative immutability library called Immutables.

Immutability Library

The alternative immutability library, Immutables, is an open source project which is operating under the Apache License 2.0. It is quite an interesting project which aims to make it easier to create immutable objects by letting users create Java classes with the processing of annotations so that you don’t have to write unnecessary boilerplate code. Sort of like Lombok, but with a more focus on immutable objects as the name suggests.

Preparing your IDE

The processing of annotations generates source classes for us, which depending on your IDE needs to be handled. I ran into some problems here with IntelliJ, so I figured it would be a good idea to share how I set up my IntelliJ to be able to handle the Immutables API.

If you don’t use IntelliJ I recommend you to simply google how to enable it, Immutables should be supported in most of the popular IDE’s.

First of all, we need to enable the autoprocessing of annotations. You can do that by opening the settings for IntelliJ and searching for Annotation Processors, and there you will want to select your module and make sure that the checkbox for Enable annotation processing and Obtain processors from classpath is selected, like the picture below.

Enabling annotation processors in IntelliJ to work with the immutability library

Additionally, as I mentioned, the annotations generates source classes for us, so we will need to make sure that the source directory is included marked as a source instead of excluded which it was for me. You can do that by going to the Project Structure menu, and going to modules, and press on generated-sources and make sure that it is marked as a Source, like the picture below.

Marking generated-sources as a source directory

And that’s it, now we should be ready to get going.

Getting started

It’s easy to get started with either Maven or Gradle. For maven simply add the following dependency.

Immutables supports two different ways of generating classes, either by using an interface or by using an abstract class. They are both very similar, and personally, I prefer to stick with interfaces. They will both be processed by annotations to generate boilerplate code for you.

Let’s start with a basic example, where we have 3 required fields and an optional one. Immutables are following good programming praxises added since Java 8 with preventing NullPointerException using java.util.Optional, check extending the builder pattern with null safety for more details. However, if you don’t like to use Optional for some reason, you can annotate an object with @Nullable. If you don’t wrap the object in an Optional or annotate it as @Nullable, then it will be treated as a required object and trigger an IllegalStateException during construction if the field is missing.

The same could be written as an abstract class if you instead would prefer that.

As mentioned, I prefer to use interfaces as it requires even less code. These classes will automatically generate a class that looks like the following.

Let’s add some tests to verify that the construction works and that the mandatory and optional parameters are considered and works as expected.

Everything good so far, we have turned around 400+ lines of code into less than 10. That’s a massive amount of boilerplate code removed. Isn’t that amazing? Our object is in fact also completely immutable, meaning that all fields are final. In fact, after building our object there isn’t even any way modify the fields, no setters or adders are provided which means that it is completely thread-safe. However, we are provided with a convenient method for modifying fields, but it will copy the object and all the fields inside. So, for example, if we provide a list to the initial object and then modify the list, it will not be the same list that we modify.

In fact, the list isn’t even modifiable outside of the object that owns the list, attempting to do that will result in an UnsupportedOperationException.

Alternative static constructor

Immutables also makes it possible to have a convenient static constructor of. This can be done by annotating fields with the annotation @Value.Parameter. However, please make sure that all mandatory fields are provided here, or you won’t even be able to compile the code.

When using an abstract class instead of an interface it is possible to add a default method by annotating @Value.Default. Which means that you do what we did above with the @Value.Parameter and skip some mandatory fields as long as you provide a default method for them.


Immutables are nice and all, but sometimes you might, for some reason, want to be able to modify the object directly. This is possible by annotating the class with @Value.Modifiable. It is worth to mention though that the support for it is quite limited as immutables, as the name suggests, heavily favors immutable objects.


Immutables is an extremely powerful immutability library to build immutable and thread-safe objects with very little boilerplate code required which makes it very convenient. The immutability library reminds quite a lot of Lombok, they both reduce boilerplate code. I would say that Lombok is much more mature. However, it lacks the same good support for immutable objects which is something that immutables excels on. So my advice is to stick to Lombok if you simply wanna reduce boilerplate code, but if you prefer immutables and functional programming in general you should definitely check out Immutables. They have loads of features than I’ve gone through, the features that I brought up is the ones I deemed most important to get intrigued and started with it. You can check out the other features supported by Immutables here.

You may also like

Leave a Reply

Your email address will not be published. Required fields are marked *