3.9 KiB

Raw Permalink Blame History

AutoValue with Builders

The introduction of this User Guide covers the basic usage of AutoValue using a static factory method as your public creation API. But in many circumstances (such as those laid out in Effective Java, 2nd Edition Item 2), you may prefer to let your callers use a builder instead.

Fortunately, AutoValue can generate builder classes too! This page explains how. Note that we recommend reading and understanding the basic usage shown in the introduction first.

How to use AutoValue with Builders

As explained in the introduction, the AutoValue concept is that you write an abstract value class, and AutoValue implements it. Builder generation works in the exact same way: you also create an abstract builder class, nesting it inside your abstract value class, and AutoValue generates implementations for both.

In `Animal.java`

import com.google.auto.value.AutoValue;

@AutoValue
abstract class Animal {
  abstract String name();
  abstract int numberOfLegs();

  static Builder builder() {
    return new AutoValue_Animal.Builder();
  }

  @AutoValue.Builder
  abstract static class Builder {
    abstract Builder setName(String value);
    abstract Builder setNumberOfLegs(int value);
    abstract Animal build();
  }
}

Note that in real life, some classes and methods would presumably be public and have Javadoc. We're leaving these off in the User Guide only to keep the examples clean and short.

Usage

public void testAnimal() {
  Animal dog = Animal.builder().setName("dog").setNumberOfLegs(4).build();
  assertEquals("dog", dog.name());
  assertEquals(4, dog.numberOfLegs());

  // You probably don't need to write assertions like these; just illustrating.
  assertTrue(
      Animal.builder().setName("dog").setNumberOfLegs(4).build().equals(dog));
  assertFalse(
      Animal.builder().setName("cat").setNumberOfLegs(4).build().equals(dog));
  assertFalse(
      Animal.builder().setName("dog").setNumberOfLegs(2).build().equals(dog));

  assertEquals("Animal{name=dog, numberOfLegs=4}", dog.toString());
}

What does AutoValue generate?

For the Animal example shown above, here is typical code AutoValue might generate.

Warnings

Be sure to put the static builder() method directly in your value class (e.g., Animal) and not the nested abstract Builder class. That ensures that the Animal class is always initialized before Builder. Otherwise you may be exposing yourself to initialization-order problems.

3.9 KiB Raw Permalink Blame History