Generated immutable value classes for Java 1.6+
Éamonn McManus, Kevin Bourrillion
Google, Inc.
“AutoValue is a great tool for eliminating the drudgery of writing mundane value classes in Java. It encapsulates much of the advice in Effective Java Chapter 2, and frees you to concentrate on the more interesting aspects of your program. The resulting program is likely to be shorter, clearer, and freer of bugs. Two thumbs up.”
-- Joshua Bloch, author, Effective Java
Value classes are extremely common in Java projects. These are classes for which you want to treat any two instances with suitably equal field values as interchangeable. That‘s right: we’re talking about those classes where you wind up implementing equals
, hashCode
and toString
in a bloated, repetitive, formulaic yet error-prone fashion.
Writing these methods the first time is not too bad, with the aid of a few helper methods and IDE templates. But once written they continue to burden reviewers, editors and future readers. Their wide expanses of boilerplate sharply decrease the signal-to-noise ratio of your code... and they love to harbor hard-to-spot bugs.
AutoValue provides an easier way to create immutable value classes, with a lot less code and less room for error, while not restricting your freedom to code almost any aspect of your class exactly the way you want it.
This page will walk you through how to use AutoValue. Looking for a little more persuasion? Please see Why AutoValue?.
The AutoValue concept is extremely simple: You write an abstract class, and AutoValue implements it. That is all there is to it; there is literally no configuration.
Note: Below, we will illustrate an AutoValue class without a generated builder class. If you're more interested in the builder support, continue reading at AutoValue with Builders instead.
Create your value class as an abstract class, with an abstract accessor method for each desired property, and bearing the @AutoValue
annotation.
import com.google.auto.value.AutoValue; @AutoValue abstract class Animal { static Animal create(String name, int numberOfLegs) { // See "How do I...?" below for nested classes. return new AutoValue_Animal(name, numberOfLegs); } abstract String name(); abstract int numberOfLegs(); }
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 short and simple.
pom.xml
Maven users should add the following to the project's pom.xml
file:
<dependency> <groupId>com.google.auto.value</groupId> <artifactId>auto-value</artifactId> <version>1.5.4</version> <scope>provided</scope> </dependency>
Gradle users should install the annotation processing plugin as described in these instructions and then use it in the build.gradle
script:
dependencies { compileOnly "com.google.auto.value:auto-value:1.5.4" apt "com.google.auto.value:auto-value:1.5.4" }
Your choice to use AutoValue is essentially API-invisible. That means that to the consumer of your class, your class looks and functions like any other. The simple test below illustrates that behavior. Note that in real life, you would write tests that actually do something interesting with the object, instead of only checking field values going in and out.
public void testAnimal() { Animal dog = Animal.create("dog", 4); assertEquals("dog", dog.name()); assertEquals(4, dog.numberOfLegs()); // You probably don't need to write assertions like these; just illustrating. assertTrue(Animal.create("dog", 4).equals(dog)); assertFalse(Animal.create("cat", 4).equals(dog)); assertFalse(Animal.create("dog", 2).equals(dog)); assertEquals("Animal{name=dog, numberOfLegs=4}", dog.toString()); }
AutoValue runs inside javac
as a standard annotation processor. It reads your abstract class and infers what the implementation class should look like. It generates source code, in your package, of a concrete implementation class which extends your abstract class, having:
equals
implementation that compares these values in the usual wayhashCode
toString
implementation returning a useful (but unspecified) string representation of the instanceYour hand-written code, as shown above, delegates its factory method call to the generated constructor and voilà!
For the Animal
example shown above, here is typical code AutoValue might generate.
Note that consumers of your value class don't need to know any of this. They just invoke your provided factory method and get a well-behaved instance back.
Be careful that you don't accidentally pass parameters to the generated constructor in the wrong order. You must ensure that your tests are sufficient to catch any field ordering problem. In most cases this should be the natural outcome from testing whatever actual purpose this value class was created for! In other cases a very simple test like the one shown above is enough. Consider switching to use the builder option to avoid this problem.
We reserve the right to change the hashCode
implementation at any time. Never persist the result of hashCode
or use it for any other unintended purpose, and be careful never to depend on the order your values appear in unordered collections like HashSet
.
See Why AutoValue?.
How do I...
equals
, etc.?equals
, etc.?compareTo
?@AutoValue
class extend another?See the links in the sidebar at the top left.