0
# Core Immutable Generation
1

2
Primary functionality for generating immutable value objects from abstract types. The `@Value.Immutable` annotation triggers the annotation processor to generate builder patterns, copy methods, validation, and standard object methods.
3

4
## Capabilities
5

6
### Value.Immutable Annotation
7

8
Instructs the processor to generate immutable implementation of abstract value type. Supports interfaces, abstract classes, and annotation types.
9

10
```java { .api }
11
/**
12
 * Generate immutable implementation of abstract value type.
13
 * Works with classes, interfaces, and annotation types including top level 
14
 * and non-private static inner types.
15
 */
16
@interface Value.Immutable {
17
    /**
18
     * Generate internal singleton object constructed without parameters.
19
     * Requires all attributes have default values.
20
     * Access via .of() static method.
21
     */
22
    boolean singleton() default false;
23
    
24
    /**
25
     * Enable strong interning - instances will be interned on construction.
26
     * Improves memory efficiency for frequently used identical objects.
27
     */
28
    boolean intern() default false;
29
    
30
    /**
31
     * Generate copying methods including static copyOf and modify-by-copy 
32
     * withAttributeName methods with structural sharing.
33
     */
34
    boolean copy() default true;
35
    
36
    /**
37
     * Precompute hashCode during construction for expensive computations
38
     * that will be used frequently in collections.
39
     */
40
    boolean prehash() default false;
41
    
42
    /**
43
     * Compute and cache hashCode on first hashCode() method call.
44
     * Alternative to prehash for deferred computation.
45
     */
46
    boolean lazyhash() default false;
47
    
48
    /**
49
     * Generate builder() factory method and Builder class.
50
     * Set to false to disable builder generation.
51
     */
52
    boolean builder() default true;
53
}
54
```
55

56
**Usage Examples:**
57

58
```java
59
// Basic immutable generation
60
@Value.Immutable
61
public interface Person {
62
    String name();
63
    int age();
64
}
65

66
// Generated: ImmutablePerson class with builder
67
Person person = ImmutablePerson.builder()
68
    .name("Alice")
69
    .age(25)
70
    .build();
71

72
// Singleton pattern for constants
73
@Value.Immutable(singleton = true)
74
public interface Empty {
75
    @Value.Default
76
    default String message() { return "empty"; }
77
}
78

79
// Access singleton via .of()
80
Empty empty = ImmutableEmpty.of();
81

82
// Performance optimizations
83
@Value.Immutable(intern = true, prehash = true)
84
public interface Coordinate {
85
    double x();
86
    double y();
87
}
88

89
// Interned instances for memory efficiency
90
Coordinate origin = ImmutableCoordinate.builder().x(0).y(0).build();
91

92
// Disable builder for parameter-only construction
93
@Value.Immutable(builder = false)
94
public interface Point {
95
    @Value.Parameter int x();
96
    @Value.Parameter int y();
97
}
98

99
// Only constructor available: ImmutablePoint.of(x, y)
100
Point point = ImmutablePoint.of(10, 20);
101
```
102

103
### Generated Implementation Structure
104

105
The annotation processor generates implementation classes with predictable structure and naming conventions.
106

107
```java { .api }
108
/**
109
 * Generated implementation class structure (example for Person interface)
110
 * 
111
 * class ImmutablePerson implements Person {
112
 *   // Private final fields for all attributes
113
 *   private final String name;
114
 *   private final int age;
115
 *   
116
 *   // Constructor (package-private or private)
117
 *   ImmutablePerson(String name, int age) { ... }
118
 *   
119
 *   // Accessor methods matching abstract type
120
 *   public String name() { return name; }
121
 *   public int age() { return age; }
122
 *   
123
 *   // Copy methods (if copy = true)
124
 *   public ImmutablePerson withName(String name) { ... }
125
 *   public ImmutablePerson withAge(int age) { ... }
126
 *   
127
 *   // Factory methods
128
 *   public static ImmutablePerson.Builder builder() { ... }
129
 *   public static ImmutablePerson copyOf(Person instance) { ... }
130
 *   
131
 *   // Standard object methods
132
 *   public boolean equals(Object obj) { ... }
133
 *   public int hashCode() { ... }
134
 *   public String toString() { ... }
135
 *   
136
 *   // Nested Builder class
137
 *   public static final class Builder { ... }
138
 * }
139
 */
140
```
141

142
### Builder Pattern Generation
143

144
Automatic generation of fluent builder classes for type-safe object construction.
145

146
```java { .api }
147
/**
148
 * Generated Builder class structure provides:
149
 * - Fluent method chaining
150
 * - Type safety at compile time
151
 * - Validation before building
152
 * - Optional from() method for copying
153
 */
154
public static final class Builder {
155
    // Setter methods for each attribute
156
    public Builder name(String name);
157
    public Builder age(int age);
158
    
159
    // Collection methods (for collection attributes)
160
    public Builder addHobbies(String element);
161
    public Builder addHobbies(String... elements);
162
    public Builder addAllHobbies(Iterable<String> elements);
163
    
164
    // Build method with validation
165
    public ImmutablePerson build();
166
    
167
    // Copy constructor (if enabled)
168
    public Builder from(Person instance);
169
}
170
```
171

172
### Copy Methods Generation
173

174
Structural sharing copy methods for efficient immutable updates.
175

176
```java { .api }
177
/**
178
 * Copy methods provide efficient immutable updates using structural sharing.
179
 * Only changed attributes create new objects; unchanged attributes are shared.
180
 */
181

182
// Modify-by-copy methods for each attribute
183
public ImmutablePerson withName(String name);
184
public ImmutablePerson withAge(int age);
185

186
// Static copy constructor
187
public static ImmutablePerson copyOf(Person instance);
188
```
189

190
**Usage Examples:**
191

192
```java
193
// Original object
194
Person person = ImmutablePerson.builder()
195
    .name("Alice")
196
    .age(25)
197
    .addHobbies("reading", "swimming")
198
    .build();
199

200
// Efficient updates with structural sharing
201
Person older = person.withAge(26);
202
Person renamed = person.withName("Alice Smith");
203

204
// Copy from existing instance
205
Person copy = ImmutablePerson.copyOf(person);
206

207
// Chain copy operations
208
Person updated = person
209
    .withAge(26)
210
    .withName("Alice Smith");
211
```