0
# Immutables Value
1
2
A comprehensive Java annotation processing framework for generating immutable value objects with builders, copy methods, and structural sharing. The library eliminates boilerplate code while providing type safety, high performance, and extensive customization options through compile-time code generation.
3
4
## Package Information
5
6
- **Package Name**: org.immutables:value
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add to your Maven `pom.xml`:
10
11
```xml
12
<dependency>
13
<groupId>org.immutables</groupId>
14
<artifactId>value</artifactId>
15
<version>1.1.3</version>
16
</dependency>
17
```
18
19
For Gradle:
20
21
```groovy
22
implementation 'org.immutables:value:1.1.3'
23
```
24
25
## Core Imports
26
27
```java
28
import org.immutables.value.Value;
29
```
30
31
For JSON marshaling:
32
33
```java
34
import org.immutables.value.Json;
35
```
36
37
For Jackson integration:
38
39
```java
40
import org.immutables.value.Jackson;
41
```
42
43
## Basic Usage
44
45
```java
46
import org.immutables.value.Value;
47
import java.util.Optional;
48
49
// Define an abstract value type
50
@Value.Immutable
51
public interface Person {
52
String name();
53
int age();
54
Optional<String> email();
55
}
56
57
// Generated implementation usage
58
public class Example {
59
public static void main(String[] args) {
60
// Create immutable instances using generated builder
61
ImmutablePerson person = ImmutablePerson.builder()
62
.name("Alice")
63
.age(30)
64
.email("alice@example.com")
65
.build();
66
67
// Copy with modifications using generated copy methods
68
ImmutablePerson olderPerson = person.withAge(31);
69
70
// Structural equality and hashCode work correctly
71
System.out.println(person.equals(olderPerson)); // false
72
System.out.println(person.name()); // "Alice"
73
System.out.println(person.toString()); // "Person{name=Alice, age=30, email=alice@example.com}"
74
}
75
}
76
```
77
78
## Architecture
79
80
Immutables uses annotation processing to generate implementations at compile-time:
81
82
- **Abstract Value Types**: Interfaces or abstract classes annotated with `@Value.Immutable`
83
- **Generated Implementations**: Concrete immutable classes with `Immutable` prefix
84
- **Builder Pattern**: Fluent builder interfaces for complex object construction
85
- **Copy Methods**: Methods prefixed with `with` for creating modified copies
86
- **Structural Sharing**: Efficient memory usage through shared immutable collections
87
- **Style System**: Comprehensive customization through `@Value.Style` annotations
88
89
The annotation processor integrates with build tools (Maven, Gradle) and IDEs, generating code that runs on JDK 6+ while supporting modern Java features.
90
91
## Capabilities
92
93
### Core Immutable Generation
94
95
Primary annotation for generating immutable value objects with builders, copy methods, validation, and comprehensive customization options.
96
97
```java { .api }
98
@interface Value.Immutable {
99
boolean singleton() default false;
100
boolean intern() default false;
101
boolean copy() default true;
102
boolean prehash() default false;
103
boolean builder() default true;
104
boolean jdkOnly() default false;
105
ImplementationVisibility visibility() default ImplementationVisibility.SAME;
106
}
107
108
enum ImplementationVisibility {
109
PUBLIC, SAME, PACKAGE, PRIVATE
110
}
111
```
112
113
[Core Immutable Generation](./core-immutable.md)
114
115
### Attribute Customization
116
117
Annotations for customizing individual attributes including default values, lazy computation, validation, and parameter ordering.
118
119
```java { .api }
120
@interface Value.Default {}
121
@interface Value.Derived {}
122
@interface Value.Lazy {}
123
@interface Value.Parameter {
124
int order() default 0;
125
}
126
@interface Value.Check {}
127
@interface Value.Auxiliary {}
128
```
129
130
[Attribute Customization](./attributes.md)
131
132
### Style and Naming Customization
133
134
Comprehensive style system for customizing generated class names, method names, builder patterns, and structural conventions.
135
136
```java { .api }
137
@interface Value.Style {
138
String[] get() default {};
139
String init() default "*";
140
String with() default "with*";
141
String add() default "add*";
142
String addAll() default "addAll*";
143
String put() default "put*";
144
String putAll() default "putAll*";
145
String copyOf() default "copyOf";
146
String of() default "of";
147
String instance() default "instance";
148
String builder() default "builder";
149
String build() default "build";
150
String typeBuilder() default "*Builder";
151
String[] typeAbstract() default {};
152
String typeImmutable() default "Immutable*";
153
String typeImmutableEnclosing() default "*";
154
String typeImmutableNested() default "*";
155
Immutable defaults() default @Immutable;
156
}
157
```
158
159
[Style and Naming](./styling.md)
160
161
### JSON Marshaling
162
163
Built-in JSON marshaling capabilities with customizable field names, subclass handling, and integration with streaming JSON APIs.
164
165
```java { .api }
166
@interface Json.Marshaled {}
167
@interface Json.Named {
168
String value();
169
}
170
@interface Json.Ignore {}
171
@interface Json.ForceEmpty {}
172
@interface Json.Import {
173
Class<?>[] value();
174
}
175
@interface Json.Subclasses {
176
Class<?>[] value();
177
}
178
```
179
180
[JSON Marshaling](./json-marshaling.md)
181
182
### Third-Party Integrations
183
184
Integration annotations for popular frameworks including Jackson, Gson, and MongoDB with seamless serialization and repository generation.
185
186
```java { .api }
187
@interface Jackson.Mapped {}
188
189
@interface Gson.TypeAdapted {}
190
@interface Gson.Named {}
191
@interface Gson.Subclasses {
192
Class<?>[] value();
193
}
194
195
@interface Mongo.Repository {
196
String value() default "";
197
}
198
@interface Mongo.Id {}
199
```
200
201
[Third-Party Integrations](./integrations.md)
202
203
### Collection Ordering
204
205
Annotations for specifying ordering behavior in generated sorted collections, supporting both natural and reverse ordering.
206
207
```java { .api }
208
@interface Value.NaturalOrder {}
209
@interface Value.ReverseOrder {}
210
```
211
212
[Collection Ordering](./collections.md)
213
214
### Bean Style Support
215
216
Annotations for generating bean-style accessors and applying conservative coding conventions for enterprise environments.
217
218
```java { .api }
219
@interface BeanStyle.Accessors {}
220
@interface BeanStyle.Conservative {}
221
```
222
223
[Bean Style Support](./bean-style.md)
224
225
### Code Generation Framework
226
227
Advanced annotation processing framework for creating custom code generators and template-based processors beyond basic immutable generation.
228
229
```java { .api }
230
@interface Generator.Template {}
231
@interface Generator.Import {
232
Class<?>[] value();
233
}
234
@interface Generator.Typedef {}
235
@interface Generator.Memoised {}
236
@interface Generator.SupportedAnnotations {
237
Class<? extends Annotation>[] value();
238
}
239
```
240
241
[Code Generation Framework](./code-generation.md)
242
243
### Runtime Marshaling Framework
244
245
Runtime utilities for JSON marshaling, async operations, and framework integrations providing serialization and database operation foundations.
246
247
```java { .api }
248
public abstract class Marshaler<T> {
249
public abstract T unmarshalInstance(JsonParser parser) throws IOException;
250
public abstract void marshalInstance(JsonGenerator generator, T instance) throws IOException;
251
public abstract Class<T> getExpectedType();
252
}
253
254
public final class Marshaling {
255
public static String toJson(Object object);
256
public static <T> T fromJson(String json, Class<? extends T> expectedType);
257
public static <T> Marshaler<T> marshalerFor(Class<? extends T> expectedType);
258
}
259
260
public interface FluentFuture<V> extends ListenableFuture<V> {
261
V getUnchecked();
262
<T> FluentFuture<T> transform(Function<? super V, ? extends T> function);
263
}
264
```
265
266
[Runtime Marshaling Framework](./runtime-marshaling.md)
267
268
## Types
269
270
```java { .api }
271
enum ImplementationVisibility {
272
PUBLIC, // Generated implementation is public
273
SAME, // Same visibility as abstract type
274
PACKAGE, // Package-private implementation
275
PRIVATE // Private implementation (requires factory methods)
276
}
277
```