Using the @Singular Annotation with Lombok Builders

1. Overview

The Lombok library provides a great way of simplifying data objects. One of the key features of Project Lombok is the @Builder annotation, which automatically creates Builder classes for creating immutable objects. However, populating collections in our objects can be clumsy with the standard Lombok-generated Builder classes.

In this tutorial, we’re going to look at the @Singular annotation, which helps us to work with collections in our data objects. It also enforces good practices, as we’ll see.

2. Builders and Collections

Builder classes make it easy to construct immutable data objects with their simple, fluent syntax. Let’s look at an example classes annotated with Lombok’s @Builder annotation:

@Getter
@Builder
public class Person {
    private final String givenName;
    private final String additionalName;
    private final String familyName;
    private final List<String> tags;
}

We can now create instances of Person using the builder pattern. Note here that the tags property is a List. Furthermore, the standard Lombok @Builder will provide methods to set this property just like for the non-list properties:

Person person = Person.builder()
  .givenName("Aaron")
  .additionalName("A")
  .familyName("Aardvark")
  .tags(Arrays.asList("fictional","incidental"))
  .build();

This is a workable but rather clumsy syntax. We can create the collection inline, as we’ve done above. Or, we can declare it ahead of time. Either way, it breaks the flow of our object creation. This is where the @Singular annotation comes in handy.

2.1. Using the @Singular Annotation with Lists

Let’s add another List to our Person object and annotate it with @Singular. This will give us a side-by-side view of one field that is annotated and one that isn’t. As well as the general tags property, we’ll add a list of interests to our Person:

@Singular private final List<String> interests;

We can now build up a list of values one at a time:

Person person = Person.builder()
  .givenName("Aaron")
  .additionalName("A")
  .familyName("Aardvark")
  .interest("history")
  .interest("sport")
  .build();

The builder will store each element internally in a List and create the appropriate Collection when we invoke build().

2.2. Working with Other Collection Types

We’ve illustrated @Singular working with a java.util.List here, but it can also be applied to other Java Collection classes. Let’s add some more members to our Person:

@Singular private final Set<String> skills;
@Singular private final Map<String, LocalDate> awards;

A Set will behave much as a List, as far as Builders are concerned – we can add elements one by one:

Person person = Person.builder()
  .givenName("Aaron")
  .skill("singing")
  .skill("dancing")
  .build();

Because Set doesn’t support duplicates, we need to be aware that adding the same element multiple times won’t create multiple elements. The Builder will handle this situation leniently. We can add an element multiple times, but the created Set will have only one occurrence of the element.

Maps are treated slightly differently, with the Builder exposing methods that take a key and value of the appropriate types:

Person person = Person.builder()
  .givenName("Aaron")
  .award("Singer of the Year", LocalDate.now().minusYears(5))
  .award("Best Dancer", LocalDate.now().minusYears(2))
  .build();

As we saw with Sets, the builder is lenient with duplicate Map keys, and will use the last value if the same key is assigned more than once.

3. Naming of @Singular Methods

So far, we’ve relied on one bit of magic in the @Singular annotation without drawing attention to it. The Builder itself provides a method for assigning the entire collection at once that uses the plural form – “awards“, for example. The extra methods added by the @Singular annotation use the singular form – for example, “award“.

Lombok is smart enough to recognize simple plural words, in English, where they follow a regular pattern. In all the examples we’ve used so far, it just removes the last ‘s’.

It will also know that, for some words ending in “es”, to remove the last two letters. It knows, for example, that “grass” is the singular of “grasses”, and that “grape”, and not “grap”, is the singular of “grapes”. In some cases, though, we have to give it some help.

Let’s build a simple model of a sea, containing fish and sea-grasses:

@Getter
@Builder
public class Sea {
    @Singular private final List<String> grasses;
    @Singular private final List<String> fish;
}

Lombok can handle the word “grasses”, but is lost with “fish”. In English, the singular and plural forms are the same, strangely enough. This code won’t compile, and we’ll get an error:

Can't singularize this name; please specify the singular explicitly (i.e. @Singular("sheep"))

We can sort things out by adding a value to the annotation to use as the singular method name:

@Singular("oneFish") private final List<String> fish;

We can now compile our code and use the Builder:

Sea sea = Sea.builder()
  .grass("Dulse")
  .grass("Kelp")
  .oneFish("Cod")
  .oneFish("Mackerel")
  .build();

In this case, we chose the rather contrived oneFish(), but the same method can be used with non-standard words that do have a distinct plural. For example, a List of children could be provided with a method child().

4. Immutability

We’ve seen how the @Singular annotation helps us to work with collections in Lombok. Besides providing convenience and expressiveness, it can also help us to keep our code clean.

Immutable objects are defined as objects that cannot be modified once they are created. Immutability is important in reactive architectures, for example, because it allows us to pass an object into a method with a guarantee of no side effects. The Builder pattern is most commonly used as an alternative to POJO getters and setters in order to support immutability.

When our data objects contain Collection classes, it can be easy to let immutability slip a little. The base collection interfaces — List, Set, and Map — all have mutable and immutable implementations. If we rely on the standard Lombok builder, we can accidentally pass in a mutable collection, and then modify it:

List<String> tags= new ArrayList();
tags.add("fictional");
tags.add("incidental");
Person person = Person.builder()
  .givenName("Aaron")
  .tags(tags)
  .build();
person.getTags().clear();
person.getTags().add("non-fictional");
person.getTags().add("important");

We’ve had to work quite hard in this simple example to make the mistake. If we’d used Arrays.asList(), for example, to construct the variable tags, we would’ve gotten an immutable list for free, and calls to add() or clear() would throw an UnsupportedOperationException.

In real coding, the error is more likely to occur if the collection is passed in as a parameter, for example. However, it’s good to know that with @Singular, we can work with the base Collection interfaces and get immutable instances when we call build().

5. Conclusion

In this tutorial, we’ve seen how the Lombok @Singular annotation provides a convenient way of working with the List, Set, and Map interfaces using the Builder pattern. The Builder pattern supports immutability, and @Singular provides us with first-class support for this.