0
# AutoValue
1

2
AutoValue is a Java annotation processor that automatically generates immutable value classes, eliminating the need to manually write repetitive equals(), hashCode(), and toString() methods. It provides a clean, declarative way to create value objects using annotations, supporting advanced features like builders, extensions for serialization and memoization, and integration with popular Java frameworks.
3

4
## Package Information
5

6
- **Package Name**: auto-value
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Group ID**: com.google.auto.value
10
- **Installation**: 
11
  ```xml
12
  <dependency>
13
    <groupId>com.google.auto.value</groupId>
14
    <artifactId>auto-value-annotations</artifactId>
15
    <version>1.11.0</version>
16
  </dependency>
17
  <dependency>
18
    <groupId>com.google.auto.value</groupId>
19
    <artifactId>auto-value</artifactId>
20
    <version>1.11.0</version>
21
    <scope>provided</scope>
22
  </dependency>
23
  ```
24

25
## Core Imports
26

27
```java
28
import com.google.auto.value.AutoValue;
29
import com.google.auto.value.AutoBuilder;
30
import com.google.auto.value.AutoAnnotation;
31
import com.google.auto.value.AutoOneOf;
32
```
33

34
## Basic Usage
35

36
```java
37
import com.google.auto.value.AutoValue;
38

39
@AutoValue
40
public abstract class Person {
41
  public static Person create(String name, int age) {
42
    return new AutoValue_Person(name, age);
43
  }
44

45
  public abstract String name();
46
  public abstract int age();
47
}
48

49
// Usage
50
Person person = Person.create("Alice", 30);
51
System.out.println(person); // Person{name=Alice, age=30}
52
System.out.println(person.equals(Person.create("Alice", 30))); // true
53
```
54

55
## Architecture
56

57
AutoValue uses annotation processing to generate implementation classes at compile time. The key components are:
58

59
- **Annotations**: Declarative markers for code generation (@AutoValue, @AutoBuilder, etc.)
60
- **Annotation Processor**: Compile-time code generator that creates implementations
61
- **Extension Framework**: Pluggable system for customizing generated code
62
- **Built-in Extensions**: Common functionality like memoization, serialization, and pretty printing
63

64
## Capabilities
65

66
### Value Class Generation
67

68
Generate immutable value classes with proper equals, hashCode, and toString implementations.
69

70
```java { .api }
71
@AutoValue
72
public abstract class YourClass {
73
  // Abstract getters define properties
74
  public abstract PropertyType propertyName();
75
  
76
  // Static factory method
77
  public static YourClass create(PropertyType propertyName) {
78
    return new AutoValue_YourClass(propertyName);
79
  }
80
}
81
```
82

83
[Value Classes](./value-classes.md)
84

85
### Builder Pattern Support
86

87
Generate builder classes for complex object construction with optional properties.
88

89
```java { .api }
90
@AutoValue
91
public abstract class YourClass {
92
  public abstract PropertyType property();
93
  
94
  public static Builder builder() {
95
    return new AutoValue_YourClass.Builder();
96
  }
97
  
98
  @AutoValue.Builder
99
  public abstract static class Builder {
100
    public abstract Builder property(PropertyType value);
101
    public abstract YourClass build();
102
  }
103
}
104
```
105

106
[Builder Pattern](./builders.md)
107

108
### Standalone Builder Generation
109

110
Generate builders for existing classes or constructors.
111

112
```java { .api }
113
@AutoBuilder(ofClass = TargetClass.class)
114
public abstract class TargetClassBuilder {
115
  public abstract TargetClassBuilder property(PropertyType value);
116
  public abstract TargetClass build();
117
  
118
  public static TargetClassBuilder builder() {
119
    return new AutoBuilder_TargetClassBuilder();
120
  }
121
}
122
```
123

124
[Standalone Builders](./standalone-builders.md)
125

126
### Annotation Implementation Generation
127

128
Generate proper annotation implementations with correct equals and hashCode.
129

130
```java { .api }
131
@AutoAnnotation
132
public static AnnotationType createAnnotation(ParamType param) {
133
  return new AutoAnnotation_ClassName_createAnnotation(param);
134
}
135
```
136

137
[Annotation Generation](./annotation-generation.md)
138

139
### Tagged Union Types
140

141
Generate tagged union (one-of) types for representing values that can be one of several types.
142

143
```java { .api }
144
@AutoOneOf(Kind.class)
145
public abstract class StringOrInteger {
146
  public enum Kind { STRING, INTEGER }
147
  
148
  public abstract Kind getKind();
149
  public abstract String string();
150
  public abstract int integer();
151
  
152
  public static StringOrInteger ofString(String s) {
153
    return AutoOneOf_StringOrInteger.string(s);
154
  }
155
  
156
  public static StringOrInteger ofInteger(int i) {
157
    return AutoOneOf_StringOrInteger.integer(i);
158
  }
159
}
160
```
161

162
[Tagged Unions](./tagged-unions.md)
163

164
### Method Memoization
165

166
Cache method results for expensive computations with thread-safe lazy initialization.
167

168
```java { .api }
169
@Memoized
170
public abstract ComputedType expensiveComputation() {
171
  return performExpensiveCalculation();
172
}
173
```
174

175
[Memoization](./memoization.md)
176

177
### Serialization Support
178

179
Generate serializable implementations for classes with non-serializable fields.
180

181
```java { .api }
182
@SerializableAutoValue
183
@AutoValue
184
public abstract class SerializableClass implements Serializable {
185
  public abstract Optional<String> optionalField();
186
  public abstract ImmutableList<Integer> listField();
187
}
188
```
189

190
[Serialization](./serialization.md)
191

192
### Pretty String Generation
193

194
Generate human-readable string representations with structured formatting.
195

196
```java { .api }
197
@ToPrettyString
198
public abstract String toPrettyString();
199
```
200

201
[Pretty String Generation](./pretty-strings.md)
202

203
### Extension Framework
204

205
Create custom extensions to modify or enhance generated code.
206

207
```java { .api }
208
public abstract class AutoValueExtension {
209
  public abstract boolean applicable(Context context);
210
  public abstract String generateClass(Context context, String className, String classToExtend, boolean isFinal);
211
}
212
```
213

214
[Extension Framework](./extensions.md)
215

216
## Core Types
217

218
```java { .api }
219
// Core annotation
220
@Retention(RetentionPolicy.CLASS)
221
@Target(ElementType.TYPE)
222
public @interface AutoValue {
223
  
224
  @Retention(RetentionPolicy.CLASS)
225
  @Target(ElementType.TYPE)
226
  public @interface Builder {}
227
  
228
  @Retention(RetentionPolicy.CLASS)
229
  @Target({ElementType.TYPE, ElementType.METHOD})
230
  public @interface CopyAnnotations {
231
    Class<? extends Annotation>[] exclude() default {};
232
  }
233
}
234

235
// Builder annotation
236
@Retention(RetentionPolicy.CLASS)
237
@Target(ElementType.TYPE)
238
public @interface AutoBuilder {
239
  String callMethod() default "";
240
  Class<?> ofClass() default Void.class;
241
}
242

243
// Annotation generation
244
@Retention(RetentionPolicy.CLASS)
245
@Target(ElementType.METHOD)
246
public @interface AutoAnnotation {}
247

248
// Tagged unions
249
@Retention(RetentionPolicy.CLASS)
250
@Target(ElementType.TYPE)
251
public @interface AutoOneOf {
252
  Class<? extends Enum<?>> value();
253
}
254
```