Lombok’s @ToString Annotation

1. Overview

As we know, the toString() method is used to get the string representation of a Java object.

Project Lombok can help us generate consistent string representations without the boilerplate and cluttering the source code. It can also improve maintainability, especially where classes might contain a large number of fields.

In this tutorial, we’ll see how to auto-generate this method and the various configuration options available to further fine-tune the resulting output.

2. Setup

Let’s start by including the Project Lombok dependency in our sample project:

<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <version>1.18.30</version>
    <scope>provided</scope>
</dependency>

In our examples, we’ll use a simple Account POJO class with a few fields to demonstrate the functionality and various configuration options.

3. Basic Usage

We can annotate any class with the Lombok @ToString annotation. This modifies the generated bytecode and creates an implementation of the toString() method.

Let’s apply this annotation to our simple Account POJO:

@ToString
public class Account {

    private String id;

    private String name;

    // standard getters and setters
}

By default, the @ToString annotation prints the class name, along with each non-static field name and its value obtained by calling the getter (if declared). The fields also appear according to the declaration order in the source class. A comma separates the different field value pairs.

Now, a call to the toString() method on an instance of this class generates this output:

Account(id=12345, name=An account)

In most cases, this is sufficient to generate a standard and useful string representation of Java objects.

4. Configuration Options

There are several configuration options available that allow us to modify and tweak the generated toString() method. These can be helpful in certain use cases. Let’s take a look at these in a little more detail.

4.1. Superclass toString()

By default, the output does not contain data from the superclass implementation of the toString() method. However, we can modify this by setting the callSuper attribute value to true:

@ToString(callSuper = true)
public class SavingAccount extends Account {
    
    private String savingAccountId;

    // standard getters and setters
}

This produces the following output with the superclass information followed by the subclass fields and values:

SavingAccount(super=Account(id=12345, name=An account), savingAccountId=6789)

Importantly, this is only really beneficial when we extend a class other than java.lang.Object. The Object implementation of toString() doesn’t provide much useful information. In other words, including this data only adds redundant information as well as increases the output verbosity.

4.2. Omitting Field Names

As we saw earlier, the default output contains field names followed by the values. However, we can omit the field names from the output by setting the includeFieldNames attribute to false in the @ToString annotation:

@ToString(includeFieldNames = false)
public class Account {

    private String id;

    private String name;

    // standard getters and setters
}

As a result, the output now shows a comma-separated list of all the field values without the field names:

Account(12345, An account)

4.3. Using Fields Instead of Getters

As we’ve already seen, the getter methods provide the field values for printing. Additionally, if the class does not contain a getter method for a particular field, then Lombok directly accesses the field and obtains its value.

However, we can configure Lombok to always use the direct field values rather than the getters by setting doNotUseGetters attribute to true:

@ToString(doNotUseGetters = true)
public class Account {

    private String id;

    private String name;

    // ignored getter
    public String getId() {
        return "this is the id:" + id;
    }

    // standard getters and setters
}

Without this attribute, we’d get the output obtained by calling the getters:

Account(id=this is the id:12345, name=An account)

Instead, with the doNotUseGetters attribute, the output actually shows the value of the id field, without invoking the getter:

Account(id=12345, name=An account)

4.4. Field Inclusion and Exclusion

Let’s say that we want to exclude certain fields from the string representation, e.g., passwords, other sensitive information, or large JSON structures. We can omit such fields simply by annotating them with the @ToString.Exclude annotation.

Let’s exclude the name field from our representation:

@ToString
public class Account {

    private String id;

    @ToString.Exclude
    private String name;

    // standard getters and setters
}

Alternatively, we can specify only the fields that are required in the output. Let’s accomplish this by using @ToString(onlyExplicitlyIncluded = true) at the class level and then annotating each required field with @ToString.Include:

@ToString(onlyExplicitlyIncluded = true)
public class Account {

    @ToString.Include
    private String id;

    private String name;

    // standard getters and setters
}

Both approaches above produce the following output with only the id field:

Account(id=12345)

In addition, Lombok output automatically excludes any variables starting with the $ symbol. However, we can override this behavior and include them by adding the @ToString.Include annotation at the field level.

4.5. Ordering Output

By default, the output contains fields according to the declaration order in the class. However, we can adjust the ordering simply by adding the rank attribute to the @ToString.Include annotation.

Let’s modify our Account class so that the id field renders before any other fields regardless of the declaration position in the class definition. We can achieve this by adding the @ToString.Include(rank = 1) annotation to the id field:

@ToString
public class Account {

    private String name;

    @ToString.Include(rank = 1)
    private String id;

    // standard getters and setters
}

Now, the id field renders first in the output despite its declaration after the name field:

Account(id=12345, name=An account)

The output contains members of a higher rank first, followed by lower ranks. The default rank value for members without the rank attribute is 0. Members with the same rank are printed according to their declaration order.

4.6. Method Output

In addition to fields, it’s also possible to include the output of an instance method that takes no arguments. We can do this by marking the no-arg instance method with @ToString.Include:

@ToString
public class Account {

    private String id;

    private String name;

    @ToString.Include
    String description() {
        return "Account description";
    }

    // standard getters and setters
}

This adds the description as the key and its output as the value to the Account representation:

Account(id=12345, name=An account, description=Account description)

If the specified method name matches a field name, then the method takes precedence over the field. In other words, the output contains the result of the method invocation instead of the matching field value.

4.7. Modifying Field Names

We can change any field name by specifying a different value in the name attribute of the @ToString.Include annotation:

@ToString
public class Account {

    @ToString.Include(name = "identification")
    private String id;

    private String name;

    // standard getters and setters
}

Now, the output contains the alternative field name from the annotation attribute instead of the actual field name:

Account(identification=12345, name=An account)

5. Printing Arrays

Arrays are printed using the Arrays.deepToString() method. This converts the array elements to their corresponding string representations. However, it’s possible that the array contains either a direct reference or an indirect circular reference.

In order to avoid infinite recursion and its associated runtime errors, this method renders any circular references to the array from within itself as “[[…]]”.

Let’s see this by adding an Object array field to our Account class:

@ToString
public class Account {

    private String id;

    private Object[] relatedAccounts;

    // standard getters and setters
}

The relatedAccounts array is now included in the output:

Account(id=12345, relatedAccounts=[54321, [...]])

Importantly, the circular reference is detected by the deepToString() method and rendered appropriately by Lombok, without causing any StackOverflowError.

6. Points to Remember

There are several details worth mentioning that are important to avoid unexpected results.

In the presence of any method named toString() in the class (regardless of the return type), Lombok does not generate its toString() method.

Different versions of Lombok may change the output format from the generated method. In any case, we should avoid code that relies on parsing the toString() method output. So this shouldn’t really be a problem.

Lastly, we can also add this annotation on enums. This produces a representation where the enum value follows the enum class name, e.g., AccounType.SAVING.

7. Conclusion

In this article, we’ve seen how to use Lombok annotations to generate a String representation of Java objects with minimum effort and boilerplate.

Initially, we looked at the basic usage, which is usually sufficient for most cases. We then covered a wide range of options available to tweak and tune the generated output.

As always, the full source code is available over on GitHub.