0
# Core Immutable Generation
1

2
Primary annotation for generating immutable value objects with builders, copy methods, validation, and comprehensive customization options. This is the fundamental capability that enables all other features in the Immutables library.
3

4
## Capabilities
5

6
### Value.Immutable Annotation
7

8
The main annotation that marks interfaces or abstract classes for immutable implementation generation.
9

10
```java { .api }
11
/**
12
 * Marks an interface or abstract class for immutable implementation generation.
13
 * Generates a concrete immutable class with builder pattern, copy methods, 
14
 * equals/hashCode, and toString implementations.
15
 */
16
@Target(ElementType.TYPE)
17
@Retention(RetentionPolicy.SOURCE)
18
@interface Value.Immutable {
19
  /** Generate singleton object pattern instead of regular immutable */
20
  boolean singleton() default false;
21
  
22
  /** Strongly intern instances on construction for memory efficiency */
23
  boolean intern() default false;
24
  
25
  /** Enable/disable copy methods (withX methods) generation */
26
  boolean copy() default true;
27
  
28
  /** Precompute hashCode during construction for performance */
29
  boolean prehash() default false;
30
  
31
  /** Enable/disable builder pattern generation */
32
  boolean builder() default true;
33
  
34
  /** Force JDK-only class usage, avoiding Guava dependencies */
35
  boolean jdkOnly() default false;
36
  
37
  /** Control visibility of generated implementation class */
38
  ImplementationVisibility visibility() default ImplementationVisibility.SAME;
39
}
40

41
enum ImplementationVisibility {
42
  PUBLIC,    // Generated implementation is public
43
  SAME,      // Same visibility as abstract type  
44
  PACKAGE,   // Package-private implementation
45
  PRIVATE    // Private implementation (requires factory methods)
46
}
47
```
48

49
**Usage Examples:**
50

51
```java
52
// Basic immutable generation
53
@Value.Immutable
54
public interface Person {
55
  String name();
56
  int age();
57
}
58

59
// Singleton pattern
60
@Value.Immutable(singleton = true)
61
public interface Config {
62
  String apiUrl();
63
  int timeout();
64
}
65

66
// High-performance settings
67
@Value.Immutable(intern = true, prehash = true)
68
public interface Coordinate {
69
  double x();
70
  double y();
71
}
72

73
// Private implementation with factory methods
74
@Value.Immutable(visibility = ImplementationVisibility.PRIVATE)
75
public interface User {
76
  String username();
77
  String email();
78
  
79
  static User of(String username, String email) {
80
    return ImmutableUser.of(username, email);
81
  }
82
}
83
```
84

85
### Value.Immutable.Include Annotation
86

87
Include external classes for processing in the same compilation round.
88

89
```java { .api }
90
/**
91
 * Include external classes for processing. Useful for processing types
92
 * that are not directly annotated but need immutable implementations.
93
 */
94
@Target(ElementType.TYPE)
95
@Retention(RetentionPolicy.SOURCE)
96
@interface Value.Immutable.Include {
97
  /** Classes to include for immutable processing */
98
  Class<?>[] value();
99
}
100
```
101

102
**Usage Example:**
103

104
```java
105
@Value.Immutable
106
@Value.Immutable.Include({ExternalType.class, AnotherType.class})
107
public interface MyType {
108
  String value();
109
}
110
```
111

112
### Nested Types
113

114
Generate nested immutable classes under an umbrella class for better organization.
115

116
```java { .api }
117
/**
118
 * Generate nested immutable classes under umbrella class.
119
 * Useful for grouping related immutable types together.
120
 */
121
@Target(ElementType.TYPE)
122
@Retention(RetentionPolicy.SOURCE)
123
@interface Value.Nested {}
124
```
125

126
**Usage Example:**
127

128
```java
129
public class Models {
130
  @Value.Immutable
131
  @Value.Nested
132
  public interface Person {
133
    String name();
134
    int age();
135
  }
136
  
137
  @Value.Immutable
138
  @Value.Nested  
139
  public interface Address {
140
    String street();
141
    String city();
142
  }
143
}
144

145
// Usage
146
Models.ImmutablePerson person = Models.ImmutablePerson.builder()
147
    .name("Alice")
148
    .age(30)
149
    .build();
150
```
151

152
### Builder Generation
153

154
Generate builders for static factory methods.
155

156
```java { .api }
157
/**
158
 * Generate builders for static factory methods.
159
 * Applied to static methods to generate builder-style creation.
160
 */
161
@Target(ElementType.METHOD)
162
@Retention(RetentionPolicy.SOURCE)
163
@interface Value.Builder {}
164
```
165

166
**Usage Example:**
167

168
```java
169
public class PersonFactory {
170
  @Value.Builder
171
  public static Person createPerson(String name, int age, Optional<String> email) {
172
    return ImmutablePerson.of(name, age, email);
173
  }
174
}
175

176
// Generated builder usage
177
Person person = new PersonFactory.CreatePersonBuilder()
178
    .name("Alice")
179
    .age(30)
180
    .email("alice@example.com")
181
    .build();
182
```
183

184
## Generated Features
185

186
When `@Value.Immutable` is applied, the annotation processor generates:
187

188
### Immutable Implementation Class
189

190
- **Naming**: `Immutable` prefix + type name (e.g., `ImmutablePerson`)
191
- **Fields**: Final fields for all attributes
192
- **Constructor**: Package-private constructor with validation
193
- **Accessors**: Methods matching abstract type signatures
194

195
### Builder Pattern
196

197
- **Builder Class**: Nested static builder class
198
- **Fluent API**: Method chaining for all attributes
199
- **Validation**: Integrated validation on `build()`
200
- **Factory Method**: Static `builder()` method on implementation
201

202
### Copy Methods
203

204
- **With Methods**: `withX()` methods for creating modified copies
205
- **Immutable Updates**: Create new instances with changed values
206
- **Null Safety**: Proper handling of optional and nullable fields
207

208
### Structural Methods
209

210
- **equals()**: Deep structural equality comparison
211
- **hashCode()**: Consistent hash code computation
212
- **toString()**: Readable string representation with all fields
213

214
### Collection Support
215

216
- **Immutable Collections**: Automatic conversion to immutable collections
217
- **Collection Builders**: Fluent API for building collections
218
- **Null Safety**: Proper handling of null collection elements